@open-webapp/calendar 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,120 @@
-# 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.
+
+## 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.refresh();
+
+<CalendarPane
+  sources={sources}
+  controller={controller}
+  selectedRsvpStatuses={statuses}          // Set<RsvpStatus>
+  onRsvpStatusesChange={setStatuses}
+/>
+```
+
+## Controller
+
+`createCalendarController({ sources, getToken, storage, crypto, now? })`
+
+- `refresh(): Promise<void>` syncs every source in parallel; never throws.
+- `getEvents(): CalendarEvent[]` stable snapshot (updated on `refresh`/`setSelectedIds`), sources concatenated in `sources` order.
+- `getSourceStatus()` / `sourceStatus`: `Record<sourceId, 'ok' | 'needs-scope' | 'error'>`.
+- `getCalendars(sourceId)`, `getSelectedIds(sourceId)`.
+- `setSelectedIds(sourceId, ids)`: primary calendar is always kept; drops events/tokens of deselected calendars, persists, notifies.
+- `clearSelectedIds(sourceId)`: same as `setSelectedIds(sourceId, [])` (leaves primary only).
+- `subscribe(listener): () => void`.
+
+### sourceStatus
+
+- `ok`: last refresh succeeded (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.
+
+## 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> }
+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.
+
+### 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).
+
+## Sync behavior
+
+- First sync per calendar: full fetch, `singleEvents=true`, window now -30d .. now +30d (RFC3339, no milliseconds), all pages (`maxResults=250`); stores `nextSyncToken`.
+- Later syncs: incremental with `syncToken` (no time bounds); cancelled items remove events.
+- HTTP 410: token dropped, full windowed resync.
+- Several sources are fetched independently; one failing source does not affect others.
+
+## 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 |
+| `emptyState?` | `ReactNode` | shown when no sources are connected |
+| `sourceNotice?` | `(source) => ReactNode` | per-source slot (e.g. re-consent button when `needs-scope`) |
+| `onClose?` | `() => void` | |
+| `popupName?` | `string` | `window.open` name for the event popup (default `notesdiary-cal-event`) |
+
+### 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; "Clear" resets to the primary calendar.
+
+### 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)

package/dist/core/controller.d.ts

@@ -0,0 +1,22 @@
+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 CalendarController {
+    refresh(): Promise<void>;
+    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,152 @@
+import { CalendarFetchError, fetchCalendarList } 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 statusSnapshot = {};
+    for (const s of sources) {
+        state.set(s.id, {
+            loaded: false,
+            events: [],
+            syncState: { tokens: {} },
+            selectedIds: [],
+            calendars: [],
+            status: 'ok',
+        });
+    }
+    function publish() {
+        snapshot = sources.flatMap((s) => state.get(s.id).events);
+        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: {} };
+            st.selectedIds = Array.isArray(row.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 refreshSource(sourceId) {
+        const st = state.get(sourceId);
+        await load(sourceId);
+        try {
+            const token = await getToken(sourceId);
+            const calendars = await fetchCalendarList(token);
+            st.calendars = calendars;
+            const selected = reconcileSelection(st.selectedIds, calendars);
+            const next = [];
+            const tokens = {};
+            for (const calendarId of selected) {
+                const res = await syncCalendar({
+                    token,
+                    sourceId,
+                    calendarId,
+                    existing: st.events.filter((e) => e.calendarId === calendarId),
+                    syncToken: st.syncState.tokens[calendarId],
+                    now: now(),
+                });
+                next.push(...res.events);
+                if (res.syncToken)
+                    tokens[calendarId] = res.syncToken;
+            }
+            st.events = next;
+            st.syncState = { tokens };
+            st.selectedIds = selected;
+            st.status = 'ok';
+            await persist(sourceId);
+        }
+        catch (e) {
+            if (e instanceof CalendarFetchError) {
+                if (e.kind === 'scope')
+                    st.status = 'needs-scope';
+                else if (e.kind !== 'network')
+                    st.status = 'error';
+            }
+            else {
+                st.status = 'error';
+            }
+        }
+    }
+    async function setSelected(sourceId, ids) {
+        const st = state.get(sourceId);
+        if (!st)
+            return;
+        await load(sourceId);
+        const primary = st.calendars.find((c) => c.primary)?.id ?? (st.selectedIds.includes('primary') ? 'primary' : undefined);
+        const next = [...new Set(primary && !ids.includes(primary) ? [primary, ...ids] : ids)];
+        st.selectedIds = next;
+        st.events = st.events.filter((e) => e.calendarId && next.includes(e.calendarId));
+        const tokens = {};
+        for (const id of next)
+            if (st.syncState.tokens[id])
+                tokens[id] = st.syncState.tokens[id];
+        st.syncState = { tokens };
+        await persist(sourceId);
+        publish();
+    }
+    const controller = {
+        async refresh() {
+            try {
+                await Promise.all(sources.map((s) => refreshSource(s.id)));
+            }
+            catch {
+                /* never throws */
+            }
+            publish();
+        },
+        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, []),
+        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 {};

package/dist/core/events.js

@@ -0,0 +1,257 @@
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+export const DEFAULT_RSVP_STATUSES = ['accepted', 'tentative', 'needsAction'];
+/** Keeps stored calendar selections that still exist, defaulting to the primary calendar. */
+export function reconcileSelectedCalendarIds(storedIds, calendars) {
+    const availableIds = new Set(calendars.map((calendar) => calendar.id));
+    const selectedIds = (storedIds ?? []).filter((id) => availableIds.has(id));
+    if (selectedIds.length > 0)
+        return selectedIds;
+    const fallback = calendars.find((calendar) => calendar.primary) ?? calendars[0];
+    return fallback ? [fallback.id] : [];
+}
+/** Filters calendars by a case-insensitive substring of their display name. */
+export function filterCalendarsByName(calendars, query) {
+    const normalizedQuery = query.toLocaleLowerCase();
+    return normalizedQuery === ''
+        ? calendars
+        : calendars.filter((calendar) => calendar.summary.toLocaleLowerCase().includes(normalizedQuery));
+}
+/** Event IDs are unique only within their calendar and source. */
+export function getCalendarEventKey(event) {
+    return `${event.sourceId}:${event.calendarId ?? ""}:${event.id}`;
+}
+/** Produces the compact calendar-selection label shown in the filter control. */
+export function summarizeCalendarSelection(selectedIds, calendars) {
+    if (selectedIds.length !== 1)
+        return `${selectedIds.length} calendars`;
+    return calendars.find((calendar) => calendar.id === selectedIds[0])?.summary ?? '1 calendar';
+}
+/** True iff the event is an all-day event. Passthrough of the package-computed flag. */
+export function isAllDay(event) {
+    return event.isAllDay;
+}
+/**
+ * Rolling fetch window: now-30d to now+30d, as full RFC3339 timestamps.
+ * Google Calendar's `timeMin`/`timeMax` reject bare `YYYY-MM-DD` dates.
+ */
+export function getRollingWindow(now) {
+    const start = new Date(now.getTime() - 30 * MS_PER_DAY);
+    const end = new Date(now.getTime() + 30 * MS_PER_DAY);
+    return { start: start.toISOString(), end: end.toISOString() };
+}
+function toIsoDate(d) {
+    return d.toISOString().slice(0, 10);
+}
+/**
+ * Returns events whose `selfResponseStatus` is a member of `selected` —
+ * declined is a normal, independently-selectable status now, not hard-excluded.
+ */
+export function filterByRsvp(events, selected) {
+    return events.filter((e) => selected.has(e.selfResponseStatus));
+}
+/** displayName -> email -> "You" (only when organizer.self is true and both above are absent). */
+export function getOrganizerLabel(event) {
+    const { organizer } = event;
+    if (organizer.displayName)
+        return organizer.displayName;
+    if (organizer.email)
+        return organizer.email;
+    if (organizer.self === true)
+        return 'You';
+    return '';
+}
+/**
+ * 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 function isEventCurrent(event, now) {
+    if (isAllDay(event))
+        return false;
+    const { start, end } = event;
+    if (!start.dateTime || !end.dateTime)
+        return false;
+    const startMs = new Date(start.dateTime).getTime();
+    const endMs = new Date(end.dateTime).getTime();
+    if (Number.isNaN(startMs) || Number.isNaN(endMs))
+        return false;
+    const nowMs = now.getTime();
+    return startMs <= nowMs && nowMs < endMs;
+}
+/**
+ * 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 function findNextUpcomingEvent(events, now) {
+    const nowMs = now.getTime();
+    let best = null;
+    let bestMs = Infinity;
+    for (const event of events) {
+        if (isAllDay(event))
+            continue;
+        const { dateTime } = event.start;
+        if (!dateTime)
+            continue;
+        const startMs = new Date(dateTime).getTime();
+        if (Number.isNaN(startMs))
+            continue;
+        if (startMs <= nowMs)
+            continue;
+        if (startMs < bestMs) {
+            bestMs = startMs;
+            best = event;
+        }
+    }
+    return best;
+}
+function getStartDateKey(event) {
+    const { start } = event;
+    if (start.date)
+        return start.date;
+    if (start.dateTime)
+        return start.dateTime.slice(0, 10);
+    return '';
+}
+function getStartTimeSortKey(event) {
+    const { start } = event;
+    if (start.dateTime)
+        return new Date(start.dateTime).getTime();
+    return -Infinity; // all-day events sort first
+}
+/**
+ * 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 function groupByDay(events, todayIso) {
+    const byDate = new Map();
+    for (const event of events) {
+        const key = getStartDateKey(event);
+        const list = byDate.get(key);
+        if (list) {
+            list.push(event);
+        }
+        else {
+            byDate.set(key, [event]);
+        }
+    }
+    if (todayIso !== undefined && !byDate.has(todayIso)) {
+        byDate.set(todayIso, []);
+    }
+    const dateKeys = Array.from(byDate.keys()).sort();
+    return dateKeys.map((dateKey) => {
+        const dayEvents = byDate.get(dateKey);
+        const allDayEvents = dayEvents.filter((e) => isAllDay(e));
+        const timedEvents = dayEvents
+            .filter((e) => !isAllDay(e))
+            .sort((a, b) => getStartTimeSortKey(a) - getStartTimeSortKey(b));
+        return { dateKey, events: [...allDayEvents, ...timedEvents] };
+    });
+}
+const MONTH_NAMES = [
+    'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+    'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
+];
+function parseIsoDateParts(dateKey) {
+    const [year, month, day] = dateKey.split('-').map(Number);
+    return { year, month, day };
+}
+function formatMonthDay(dateKey, includeYear) {
+    const { year, month, day } = parseIsoDateParts(dateKey);
+    const monthName = MONTH_NAMES[month - 1];
+    const base = `${monthName} ${day}`;
+    return includeYear ? `${base}, ${year}` : base;
+}
+function addDaysToIso(dateKey, days) {
+    const { year, month, day } = parseIsoDateParts(dateKey);
+    const d = new Date(Date.UTC(year, month - 1, day));
+    d.setUTCDate(d.getUTCDate() + days);
+    return toIsoDate(d);
+}
+/**
+ * "Today · Sept 26" / "Tomorrow · Sept 27" / else "Sept 28"-style.
+ * Includes year only when the event's year differs from today's year.
+ */
+export function formatDayHeader(dateKey, today) {
+    const { year: todayYear } = parseIsoDateParts(today);
+    const { year: eventYear } = parseIsoDateParts(dateKey);
+    const includeYear = eventYear !== todayYear;
+    const monthDay = formatMonthDay(dateKey, includeYear);
+    if (dateKey === today)
+        return `Today · ${monthDay}`;
+    if (dateKey === addDaysToIso(today, 1))
+        return `Tomorrow · ${monthDay}`;
+    return monthDay;
+}
+const JOIN_URL_REGEX = /https?:\/\/[^\s<>"']*(?:zoom\.us|meet\.google\.com|teams\.microsoft\.com)[^\s<>"']*/i;
+export function deriveSelfResponseStatus(raw) {
+    if (!Array.isArray(raw.attendees))
+        return 'accepted';
+    const status = raw.attendees.find((a) => a?.self === true)?.responseStatus;
+    if (status === 'accepted' || status === 'tentative' || status === 'needsAction' || status === 'declined') {
+        return status;
+    }
+    return 'needsAction';
+}
+export function extractJoinUrl(raw) {
+    if (raw.hangoutLink)
+        return raw.hangoutLink;
+    const video = raw.conferenceData?.entryPoints?.find((ep) => ep.entryPointType === 'video');
+    if (video?.uri)
+        return video.uri;
+    const loc = typeof raw.location === 'string' ? raw.location.match(JOIN_URL_REGEX) : null;
+    if (loc)
+        return loc[0];
+    const desc = typeof raw.description === 'string' ? raw.description.match(JOIN_URL_REGEX) : null;
+    return desc ? desc[0] : null;
+}
+/** Parses a raw Google Calendar event. Returns null for cancelled/malformed input; never throws. */
+export function parseEvent(raw, ctx) {
+    try {
+        if (!raw || typeof raw !== 'object')
+            return null;
+        if (typeof raw.id !== 'string' || raw.id === '')
+            return null;
+        if (raw.status === 'cancelled')
+            return null;
+        const start = raw.start ?? {};
+        const end = raw.end ?? {};
+        return {
+            id: raw.id,
+            sourceId: ctx.sourceId,
+            calendarId: ctx.calendarId,
+            summary: raw.summary ?? '',
+            start: { dateTime: start.dateTime, date: start.date, timeZone: start.timeZone },
+            end: { dateTime: end.dateTime, date: end.date, timeZone: end.timeZone },
+            isAllDay: Boolean(start.date && !start.dateTime),
+            selfResponseStatus: deriveSelfResponseStatus(raw),
+            joinUrl: extractJoinUrl(raw),
+            organizer: {
+                displayName: raw.organizer?.displayName,
+                email: raw.organizer?.email,
+                self: Boolean(raw.organizer?.self),
+            },
+            htmlLink: raw.htmlLink ?? '',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function parseEvents(items, ctx) {
+    const out = [];
+    if (!Array.isArray(items))
+        return out;
+    for (const item of items) {
+        const e = parseEvent(item, ctx);
+        if (e)
+            out.push(e);
+    }
+    return out;
+}

package/dist/core/fetch.d.ts

@@ -0,0 +1,17 @@
+import type { CalendarInfo } from './types.js';
+export declare class CalendarFetchError extends Error {
+    kind: 'network' | 'auth' | 'scope' | 'gone' | 'http';
+    status: number;
+    constructor(kind: 'network' | 'auth' | 'scope' | 'gone' | 'http', status?: number);
+}
+export declare function fetchCalendarList(token: string): Promise<CalendarInfo[]>;
+export interface EventsPage {
+    items: any[];
+    nextSyncToken?: string;
+}
+/** Fetches all pages of events. With syncToken, no time bounds are sent (the API forbids them). */
+export declare function fetchEvents(token: string, calendarId: string, opts: {
+    syncToken?: string;
+    timeMin?: string;
+    timeMax?: string;
+}): Promise<EventsPage>;