@pellux/goodvibes-sdk 0.38.0 → 1.0.0

package/dist/platform/calendar/ics-parser.js

@@ -0,0 +1,236 @@
+/**
+ * ics-parser.ts — a pure, dependency-free iCalendar (RFC 5545) reader.
+ *
+ * Vendored on purpose. The SDK's `packages/sdk` ships ZERO third-party runtime
+ * dependencies (workspace packages only — see packages/sdk/package.json), and it
+ * guards that with bundle-budget / browser-compat / no-any gates. Pulling a general
+ * ICS library in for the read-focused subset we actually need would break that
+ * convention for little gain; this focused reader matches repo style and is easy to
+ * hold honest. See the decision record for the vendored-vs-dependency ruling and the
+ * exact supported subset.
+ *
+ * Scope of what this reads (documented, not faked):
+ *  - VCALENDAR framing, X-WR-CALNAME for a calendar display name.
+ *  - VEVENT: UID, SUMMARY, LOCATION, DESCRIPTION, DTSTART, DTEND, RRULE.
+ *  - DTSTART/DTEND as VALUE=DATE ('YYYYMMDD') or date-time ('YYYYMMDDTHHMMSS'),
+ *    with honest zone anchoring: trailing 'Z' => utc; TZID=... => tzid (wall time
+ *    kept, NOT offset-converted, because this build has no tz database); otherwise
+ *    floating. RRULE is captured raw and handed to the recurrence expander.
+ *  - RFC 5545 line unfolding (a leading space/tab continues the previous line) and
+ *    TEXT unescaping (\\n \\, \\; \\, \\\\).
+ *
+ * Everything unrecognised is ignored quietly EXCEPT the two things a caller must be
+ * told about: a VEVENT with no usable DTSTART is `skipped` with a reason, and an
+ * RRULE we do not fully expand is flagged on the event (in rrule.ts) — never dropped.
+ *
+ * PURE: no fs, no network, no process globals. Input is text; output is data.
+ */
+import { describeRecurrence } from './rrule.js';
+/**
+ * Unfold physical lines into logical content lines (RFC 5545 §3.1). A line beginning
+ * with a single space or tab is a continuation of the previous line.
+ */
+function unfold(text) {
+    const physical = text.split(/\r\n|\r|\n/);
+    const out = [];
+    for (let i = 0; i < physical.length; i++) {
+        const cur = physical[i] ?? '';
+        if ((cur.startsWith(' ') || cur.startsWith('\t')) && out.length > 0) {
+            out[out.length - 1].raw += cur.slice(1);
+        }
+        else {
+            out.push({ raw: cur, line: i + 1 });
+        }
+    }
+    return out;
+}
+/** Parse one content line into name/params/value (RFC 5545 §3.1). */
+function parseContentLine(raw, line) {
+    const colon = raw.indexOf(':');
+    if (colon < 0)
+        return undefined;
+    const head = raw.slice(0, colon);
+    const value = raw.slice(colon + 1);
+    const segments = head.split(';');
+    const name = (segments[0] ?? '').trim().toUpperCase();
+    if (name === '')
+        return undefined;
+    const params = new Map();
+    for (let i = 1; i < segments.length; i++) {
+        const seg = segments[i] ?? '';
+        const eq = seg.indexOf('=');
+        if (eq < 0)
+            continue;
+        const pName = seg.slice(0, eq).trim().toUpperCase();
+        let pVal = seg.slice(eq + 1).trim();
+        if (pVal.startsWith('"') && pVal.endsWith('"'))
+            pVal = pVal.slice(1, -1);
+        params.set(pName, pVal);
+    }
+    return { name, params, value, line };
+}
+/** Unescape RFC 5545 TEXT (\\n, \\N, \\,, \\;, \\\\). */
+function unescapeText(value) {
+    let out = '';
+    for (let i = 0; i < value.length; i++) {
+        const ch = value[i];
+        if (ch === '\\' && i + 1 < value.length) {
+            const next = value[i + 1];
+            if (next === 'n' || next === 'N')
+                out += '\n';
+            else if (next === ',' || next === ';' || next === '\\')
+                out += next;
+            else
+                out += next;
+            i++;
+        }
+        else {
+            out += ch ?? '';
+        }
+    }
+    return out;
+}
+const DATE_ONLY = /^(\d{4})(\d{2})(\d{2})$/;
+const DATE_TIME = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(Z)?$/;
+/** Parse a DTSTART/DTEND value + params into an honest EventDateTime, or undefined. */
+function parseDateValue(value, params) {
+    const trimmed = value.trim();
+    const isDateParam = params.get('VALUE') === 'DATE';
+    const tzid = params.get('TZID');
+    const dateMatch = DATE_ONLY.exec(trimmed);
+    if (dateMatch && (isDateParam || !trimmed.includes('T'))) {
+        const [, y, m, d] = dateMatch;
+        return { value: `${y}-${m}-${d}`, kind: 'date', zone: 'floating' };
+    }
+    const dtMatch = DATE_TIME.exec(trimmed);
+    if (dtMatch) {
+        const [, y, m, d, hh, mm, ss, z] = dtMatch;
+        const local = `${y}-${m}-${d}T${hh}:${mm}:${ss}`;
+        if (z === 'Z') {
+            return { value: `${local}Z`, kind: 'date-time', zone: 'utc' };
+        }
+        if (tzid) {
+            return { value: local, kind: 'date-time', zone: 'tzid', tzid };
+        }
+        return { value: local, kind: 'date-time', zone: 'floating' };
+    }
+    return undefined;
+}
+let syntheticCounter = 0;
+/** Build a stable synthetic UID for a VEVENT that omitted one. */
+function syntheticUid(start, summary) {
+    syntheticCounter += 1;
+    const stamp = start?.value ?? 'no-start';
+    const slug = summary.replace(/\s+/g, '-').slice(0, 24) || 'event';
+    return `synthetic:${slug}:${stamp}:${syntheticCounter}`;
+}
+/**
+ * Parse .ics text into typed events plus honest skip/diagnostic lists.
+ *
+ * @param text raw .ics content (file body or fetched feed body).
+ */
+export function parseIcs(text) {
+    const lines = unfold(text);
+    const events = [];
+    const skipped = [];
+    const diagnostics = [];
+    let calendarName;
+    let inEvent = false;
+    let draft;
+    for (const { raw, line } of lines) {
+        if (raw.trim() === '')
+            continue;
+        const cl = parseContentLine(raw, line);
+        if (!cl)
+            continue;
+        if (cl.name === 'BEGIN' && cl.value.trim().toUpperCase() === 'VEVENT') {
+            inEvent = true;
+            draft = { startLine: line };
+            continue;
+        }
+        if (cl.name === 'END' && cl.value.trim().toUpperCase() === 'VEVENT') {
+            if (draft)
+                finalizeEvent(draft, events, skipped, diagnostics);
+            inEvent = false;
+            draft = undefined;
+            continue;
+        }
+        if (!inEvent) {
+            if (cl.name === 'X-WR-CALNAME')
+                calendarName = unescapeText(cl.value).trim();
+            continue;
+        }
+        if (!draft)
+            continue;
+        switch (cl.name) {
+            case 'UID':
+                draft.uid = cl.value.trim();
+                break;
+            case 'SUMMARY':
+                draft.summary = unescapeText(cl.value);
+                break;
+            case 'LOCATION':
+                draft.location = unescapeText(cl.value);
+                break;
+            case 'DESCRIPTION':
+                draft.description = unescapeText(cl.value);
+                break;
+            case 'DTSTART': {
+                const parsed = parseDateValue(cl.value, cl.params);
+                if (parsed)
+                    draft.start = parsed;
+                else
+                    diagnostics.push({ line: cl.line, component: 'DTSTART', message: `Unrecognised DTSTART value '${cl.value.trim()}' — event kept without a usable start.` });
+                break;
+            }
+            case 'DTEND': {
+                const parsed = parseDateValue(cl.value, cl.params);
+                if (parsed)
+                    draft.end = parsed;
+                else
+                    diagnostics.push({ line: cl.line, component: 'DTEND', message: `Unrecognised DTEND value '${cl.value.trim()}' — event kept without an end.` });
+                break;
+            }
+            case 'RRULE':
+                draft.rrule = cl.value.trim();
+                break;
+            default:
+                break;
+        }
+    }
+    if (inEvent && draft) {
+        diagnostics.push({ line: draft.startLine, component: 'VEVENT', message: 'VEVENT was not closed with END:VEVENT before end of feed — finalised anyway.' });
+        finalizeEvent(draft, events, skipped, diagnostics);
+    }
+    return {
+        ...(calendarName !== undefined ? { calendarName } : {}),
+        events,
+        skipped,
+        diagnostics,
+    };
+}
+function finalizeEvent(draft, events, skipped, diagnostics) {
+    if (!draft.start) {
+        skipped.push({ line: draft.startLine, component: 'VEVENT', message: `Skipped VEVENT '${draft.summary ?? draft.uid ?? 'untitled'}' — no usable DTSTART.` });
+        return;
+    }
+    const summary = draft.summary ?? '(no title)';
+    const uid = draft.uid && draft.uid !== '' ? draft.uid : syntheticUid(draft.start, summary);
+    let recurrence;
+    if (draft.rrule) {
+        recurrence = describeRecurrence(draft.rrule);
+        if (recurrence.expansion === 'unsupported' && recurrence.unsupportedReason) {
+            diagnostics.push({ line: draft.startLine, component: 'RRULE', message: `Event '${summary}': ${recurrence.unsupportedReason}` });
+        }
+    }
+    const event = {
+        uid,
+        summary,
+        ...(draft.location !== undefined ? { location: draft.location } : {}),
+        ...(draft.description !== undefined ? { description: draft.description } : {}),
+        start: draft.start,
+        ...(draft.end !== undefined ? { end: draft.end } : {}),
+        ...(recurrence !== undefined ? { recurrence } : {}),
+    };
+    events.push(event);
+}

package/dist/platform/calendar/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @pellux/goodvibes-sdk/platform/calendar
+ *
+ * External-calendar READ connectivity — the SDK machinery behind the agent's
+ * `/calendar import`, `/calendar subscribe`, and the connect wizard (One-Platform
+ * Wave 4, A9). Two pieces, both honest by construction:
+ *
+ *  - A vendored iCalendar (RFC 5545) reader: `parseIcs` turns .ics text (a file body
+ *    or a fetched feed) into typed events, and `expandEvent` expands the honest RRULE
+ *    subset into concrete occurrences. A recurrence outside the subset is NEVER
+ *    fabricated — the event keeps its seed and carries an explicit
+ *    `recurrence.expansion: 'unsupported'` marker naming the part we declined.
+ *  - `SubscriptionStore`: named external-calendar feed subscriptions with per-feed
+ *    honest status (ok / stale-with-age / unreachable / parse-error), etag/
+ *    last-modified conditional refresh, and a paste-URL-and-done `add()` that
+ *    validates by fetching and auto-derives the name from X-WR-CALNAME.
+ *
+ * Network and clock are INJECTED (FeedFetcher / Clock) — this module never reaches
+ * the network or reads wall-clock on its own, so consumers (and tests, with fake
+ * feeds) own the IO boundary entirely. Persistence is the caller's job.
+ *
+ * The daemon `calendar.*` operator methods stay `invokable: false` — they are
+ * CalDAV-backed contracts with no live route, a separate concern from this
+ * read-focused file/feed machinery. See
+ * docs/decisions/2026-07-05-calendar-connectivity-sdk-extraction.md.
+ */
+export { parseIcs } from './ics-parser.js';
+export { describeRecurrence, expandEvent } from './rrule.js';
+export { SubscriptionStore, maskFeedUrl, DEFAULT_REFRESH_INTERVAL_MS, MIN_REFRESH_INTERVAL_MS, MAX_REFRESH_INTERVAL_MS, type SubscriptionStoreOptions, type AddSubscriptionInput, type AddResult, type ValidationResult, } from './subscription-store.js';
+export type { CalendarEvent, EventDateTime, EventZone, RecurrenceInfo, RecurrenceExpansion, ParsedCalendar, ParseDiagnostic, EventOccurrence, DateWindow, CalendarSubscription, SubscriptionHealth, SubscriptionSnapshot, RefreshReport, FeedFetcher, FeedFetchRequest, FeedFetchResult, Clock, } from './types.js';
+export { GOOGLE_PROFILE, MICROSOFT_PROFILE, GOOGLE_PLACEHOLDER_CLIENT_ID, MICROSOFT_PLACEHOLDER_CLIENT_ID, GOOGLE_SCOPES_DEFAULT, MICROSOFT_SCOPES_DEFAULT, PROVIDER_SETUP_STEPS, providerProfile, resolveClientConfig, } from './oauth-providers.js';
+export { OAuthFlowError, createPkcePair, parseTokenResponse, beginAuthCodeFlow, completeAuthCodeFlow, beginDeviceCodeFlow, pollDeviceCodeFlow, refreshAccessToken, revokeToken, type PkcePair, type Sleep, } from './oauth-flow.js';
+export { CalendarTokenStore, TokenRefreshError, type CalendarTokenStoreOptions, } from './oauth-token-store.js';
+export { normalizeGoogleEvent, normalizeGraphEvent, normalizeOffsetDateTime, eventDateTimeEpochMs, compareEventDateTime, compareMergedCalendarEventsByStart, } from './merged-calendar-model.js';
+export { CalendarApiError, authedRequest, errorFromResponse, } from './calendar-api-shared.js';
+export { listGoogleCalendars, listGoogleEvents, createGoogleEvent, type GoogleEventsQuery, } from './google-calendar-api.js';
+export { listGraphCalendars, listGraphEvents, createGraphEvent, type GraphEventsQuery, } from './microsoft-graph-api.js';
+export { CalendarConnector, type CalendarConnectorOptions, type EventWindow, } from './calendar-connector.js';
+export { fetchAdapter } from './http-fetch-adapter.js';
+export type { CalendarProviderId, CalendarSource, OAuthProviderProfile, OAuthClientOverrides, ResolvedClientConfig, HttpFetch, HttpRequest, HttpResponse, LoopbackWaiter, LoopbackListenerFactory, SecretStoreSlice, StoredTokenSet, ConnectionState, FlowFailureReason, AuthCodeFlowStart, DeviceCodeFlowStart, ApiDegradedState, MergedCalendarEvent, ProviderCalendar, NewCalendarEvent, ConnectedAccount, } from './oauth-types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/platform/calendar/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/platform/calendar/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,2BAA2B,EAC3B,uBAAuB,EACvB,uBAAuB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EACV,aAAa,EACb,aAAa,EACb,SAAS,EACT,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,eAAe,EACf,UAAU,EACV,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,KAAK,GACN,MAAM,YAAY,CAAC;AAcpB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,4BAA4B,EAC5B,+BAA+B,EAC/B,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,eAAe,EACf,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,KAAK,QAAQ,EACb,KAAK,KAAK,GACX,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,yBAAyB,GAC/B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,kCAAkC,GACnC,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,iBAAiB,GACvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,KAAK,gBAAgB,GACtB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,WAAW,GACjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,SAAS,EACT,WAAW,EACX,YAAY,EACZ,cAAc,EACd,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC"}

package/dist/platform/calendar/index.js

@@ -0,0 +1,49 @@
+/**
+ * @pellux/goodvibes-sdk/platform/calendar
+ *
+ * External-calendar READ connectivity — the SDK machinery behind the agent's
+ * `/calendar import`, `/calendar subscribe`, and the connect wizard (One-Platform
+ * Wave 4, A9). Two pieces, both honest by construction:
+ *
+ *  - A vendored iCalendar (RFC 5545) reader: `parseIcs` turns .ics text (a file body
+ *    or a fetched feed) into typed events, and `expandEvent` expands the honest RRULE
+ *    subset into concrete occurrences. A recurrence outside the subset is NEVER
+ *    fabricated — the event keeps its seed and carries an explicit
+ *    `recurrence.expansion: 'unsupported'` marker naming the part we declined.
+ *  - `SubscriptionStore`: named external-calendar feed subscriptions with per-feed
+ *    honest status (ok / stale-with-age / unreachable / parse-error), etag/
+ *    last-modified conditional refresh, and a paste-URL-and-done `add()` that
+ *    validates by fetching and auto-derives the name from X-WR-CALNAME.
+ *
+ * Network and clock are INJECTED (FeedFetcher / Clock) — this module never reaches
+ * the network or reads wall-clock on its own, so consumers (and tests, with fake
+ * feeds) own the IO boundary entirely. Persistence is the caller's job.
+ *
+ * The daemon `calendar.*` operator methods stay `invokable: false` — they are
+ * CalDAV-backed contracts with no live route, a separate concern from this
+ * read-focused file/feed machinery. See
+ * docs/decisions/2026-07-05-calendar-connectivity-sdk-extraction.md.
+ */
+export { parseIcs } from './ics-parser.js';
+export { describeRecurrence, expandEvent } from './rrule.js';
+export { SubscriptionStore, maskFeedUrl, DEFAULT_REFRESH_INTERVAL_MS, MIN_REFRESH_INTERVAL_MS, MAX_REFRESH_INTERVAL_MS, } from './subscription-store.js';
+// ---------------------------------------------------------------------------
+// Authenticated provider connectivity — Google Calendar API v3 + Microsoft Graph
+// over OAuth 2.0 (One-Platform Wave 4, A10). This half connects to real accounts;
+// A9's half above reads .ics files and feeds. Both normalize into ONE merged event
+// model (see MergedCalendarEvent) that a unified /calendar view renders source-
+// labeled (google-api / microsoft-graph / ics-feed / local).
+//
+// The network is an injected HttpFetch, the loopback redirect an injected
+// LoopbackWaiter, token persistence an injected secret-store slice — so the full
+// OAuth + API flow runs against fake servers with no real network, port, or keychain.
+// See docs/decisions/2026-07-06-calendar-oauth-connector-sdk.md.
+export { GOOGLE_PROFILE, MICROSOFT_PROFILE, GOOGLE_PLACEHOLDER_CLIENT_ID, MICROSOFT_PLACEHOLDER_CLIENT_ID, GOOGLE_SCOPES_DEFAULT, MICROSOFT_SCOPES_DEFAULT, PROVIDER_SETUP_STEPS, providerProfile, resolveClientConfig, } from './oauth-providers.js';
+export { OAuthFlowError, createPkcePair, parseTokenResponse, beginAuthCodeFlow, completeAuthCodeFlow, beginDeviceCodeFlow, pollDeviceCodeFlow, refreshAccessToken, revokeToken, } from './oauth-flow.js';
+export { CalendarTokenStore, TokenRefreshError, } from './oauth-token-store.js';
+export { normalizeGoogleEvent, normalizeGraphEvent, normalizeOffsetDateTime, eventDateTimeEpochMs, compareEventDateTime, compareMergedCalendarEventsByStart, } from './merged-calendar-model.js';
+export { CalendarApiError, authedRequest, errorFromResponse, } from './calendar-api-shared.js';
+export { listGoogleCalendars, listGoogleEvents, createGoogleEvent, } from './google-calendar-api.js';
+export { listGraphCalendars, listGraphEvents, createGraphEvent, } from './microsoft-graph-api.js';
+export { CalendarConnector, } from './calendar-connector.js';
+export { fetchAdapter } from './http-fetch-adapter.js';

package/dist/platform/calendar/merged-calendar-model.d.ts

@@ -0,0 +1,67 @@
+/**
+ * merged-calendar-model.ts — normalization of provider (Google Calendar API v3,
+ * Microsoft Graph) events into the ONE merged event model shared with A9's .ics
+ * path: A9's CalendarEvent shape plus a source label and the provider ids.
+ *
+ * Time-anchoring honesty follows A9's contract (this build ships no tz database):
+ *  - An all-day value keeps its 'YYYY-MM-DD' date and is `zone: 'floating'`.
+ *  - A timed value carrying an explicit numeric offset or a trailing Z is normalized
+ *    to a real UTC instant (`zone: 'utc'`) — a fixed-offset -> UTC shift is pure
+ *    arithmetic, NOT a named-zone conversion, so it is lossless and honest.
+ *  - A timed value that only names a zone (no offset) is kept as wall time with the
+ *    TZID recorded (`zone: 'tzid'`), never converted.
+ *
+ * Recurrence is delegated to the provider: the API clients request expanded single
+ * instances (Google singleEvents=true, Graph calendarView), so each normalized event
+ * is one concrete occurrence — no rule is fabricated here.
+ */
+import type { EventDateTime } from './types.js';
+import type { MergedCalendarEvent } from './oauth-types.js';
+/**
+ * Normalize one Google event (already a concrete instance from singleEvents=true)
+ * into the merged model. Returns null for an event with no usable start.
+ */
+export declare function normalizeGoogleEvent(raw: unknown, calendarId: string, calendarLabel: string): MergedCalendarEvent | null;
+/** Normalize one Graph event (a concrete instance from calendarView) into the model. */
+export declare function normalizeGraphEvent(raw: unknown, calendarId: string, calendarLabel: string): MergedCalendarEvent | null;
+/**
+ * Normalize a date-time that may carry a numeric offset or trailing Z into a real
+ * UTC instant. A value with only a named zone (no offset) is impossible here (the
+ * Google API always includes an offset on dateTime), but we defend: if Date cannot
+ * parse it, keep the wall value as tzid when a zone was named, else floating.
+ */
+export declare function normalizeOffsetDateTime(value: string, namedZone?: string): EventDateTime;
+/**
+ * Best-effort epoch (ms) for one {@link EventDateTime}, for sorting a mixed list of
+ * merged events across zones/kinds. THIS IS THE ONE DOCUMENTED FUNCTION every
+ * consumer should sort through — a raw `localeCompare`/string sort on `.value` looks
+ * like it works (ISO strings are lexicographically sortable) but silently produces
+ * the wrong order the moment a `zone: 'utc'` value (a real instant) is compared
+ * against a `zone: 'tzid'` or `zone: 'floating'` value (a wall-clock reading with an
+ * unknown or undeclared offset) — e.g. a `tzid` event at `01:00` in
+ * `America/New_York` and a `utc` event at `05:00Z` are close to the same real
+ * instant (EDT is UTC-4), but a naive string/localeCompare sort of `'01:00:00'` vs
+ * `'05:00:00Z'` treats them as 4-5 hours apart on the SAME axis, which they are not.
+ *
+ * Documented approximation (this build ships no tz database, so a true conversion is
+ * not possible):
+ *  - `kind: 'date'` (all-day) => midnight UTC of that date.
+ *  - `zone: 'utc'` => the real epoch, via `Date.parse` of the (already-normalized,
+ *    Z-suffixed) ISO value. Authoritative.
+ *  - `zone: 'tzid'` or `zone: 'floating'` => the wall-clock digits are read AS IF
+ *    they were UTC (no offset applied). This is an approximation, not the true
+ *    instant — it keeps events within the SAME zone in correct relative order, and
+ *    gives cross-zone comparisons a deterministic (if approximate) answer instead of
+ *    an arbitrary one.
+ */
+export declare function eventDateTimeEpochMs(dt: EventDateTime): number;
+/**
+ * Chronological comparator for {@link EventDateTime} values (ascending), suitable
+ * for `Array.prototype.sort`. See {@link eventDateTimeEpochMs} for the documented
+ * cross-zone approximation this is built on — this is the ONE function every
+ * consumer should sort through instead of inventing its own string comparison.
+ */
+export declare function compareEventDateTime(a: EventDateTime, b: EventDateTime): number;
+/** Sort {@link MergedCalendarEvent}s by start time, through {@link compareEventDateTime}. */
+export declare function compareMergedCalendarEventsByStart(a: MergedCalendarEvent, b: MergedCalendarEvent): number;
+//# sourceMappingURL=merged-calendar-model.d.ts.map

package/dist/platform/calendar/merged-calendar-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merged-calendar-model.d.ts","sourceRoot":"","sources":["../../../src/platform/calendar/merged-calendar-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAsB,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAiChF;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EACZ,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,mBAAmB,GAAG,IAAI,CAmB5B;AAqCD,wFAAwF;AACxF,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,OAAO,EACZ,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,mBAAmB,GAAG,IAAI,CAqB5B;AAMD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,CAUxF;AAiBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,aAAa,GAAG,MAAM,CAe9D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,MAAM,CAE/E;AAED,6FAA6F;AAC7F,wBAAgB,kCAAkC,CAAC,CAAC,EAAE,mBAAmB,EAAE,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAEzG"}

package/dist/platform/calendar/merged-calendar-model.js

@@ -0,0 +1,181 @@
+/**
+ * merged-calendar-model.ts — normalization of provider (Google Calendar API v3,
+ * Microsoft Graph) events into the ONE merged event model shared with A9's .ics
+ * path: A9's CalendarEvent shape plus a source label and the provider ids.
+ *
+ * Time-anchoring honesty follows A9's contract (this build ships no tz database):
+ *  - An all-day value keeps its 'YYYY-MM-DD' date and is `zone: 'floating'`.
+ *  - A timed value carrying an explicit numeric offset or a trailing Z is normalized
+ *    to a real UTC instant (`zone: 'utc'`) — a fixed-offset -> UTC shift is pure
+ *    arithmetic, NOT a named-zone conversion, so it is lossless and honest.
+ *  - A timed value that only names a zone (no offset) is kept as wall time with the
+ *    TZID recorded (`zone: 'tzid'`), never converted.
+ *
+ * Recurrence is delegated to the provider: the API clients request expanded single
+ * instances (Google singleEvents=true, Graph calendarView), so each normalized event
+ * is one concrete occurrence — no rule is fabricated here.
+ */
+function googleDateTime(value) {
+    if (!value)
+        return null;
+    if (typeof value.date === 'string') {
+        return { value: value.date, kind: 'date', zone: 'floating' };
+    }
+    if (typeof value.dateTime === 'string') {
+        return normalizeOffsetDateTime(value.dateTime, typeof value.timeZone === 'string' ? value.timeZone : undefined);
+    }
+    return null;
+}
+/**
+ * Normalize one Google event (already a concrete instance from singleEvents=true)
+ * into the merged model. Returns null for an event with no usable start.
+ */
+export function normalizeGoogleEvent(raw, calendarId, calendarLabel) {
+    const ev = (raw ?? {});
+    const start = googleDateTime(ev.start);
+    if (!start)
+        return null;
+    const id = typeof ev.id === 'string' ? ev.id : undefined;
+    const uid = typeof ev.iCalUID === 'string' && ev.iCalUID.length > 0 ? ev.iCalUID : id ?? syntheticUid('google', calendarId);
+    const end = googleDateTime(ev.end);
+    return {
+        uid,
+        summary: typeof ev.summary === 'string' ? ev.summary : '(no title)',
+        ...(typeof ev.location === 'string' ? { location: ev.location } : {}),
+        ...(typeof ev.description === 'string' ? { description: ev.description } : {}),
+        start,
+        ...(end ? { end } : {}),
+        source: 'google-api',
+        ...(id ? { sourceEventId: id } : {}),
+        calendarId,
+        calendarLabel,
+    };
+}
+function graphDateTime(value, isAllDay) {
+    if (!value || typeof value.dateTime !== 'string')
+        return null;
+    const zone = typeof value.timeZone === 'string' ? value.timeZone : 'UTC';
+    if (isAllDay) {
+        // Graph all-day start is midnight; keep the date part as a floating date.
+        return { value: value.dateTime.slice(0, 10), kind: 'date', zone: 'floating' };
+    }
+    if (zone === 'UTC') {
+        // Graph returns UTC wall time without an offset; stamp it as real UTC.
+        const iso = value.dateTime.endsWith('Z') ? isoSeconds(value.dateTime) : `${isoSeconds(value.dateTime)}Z`;
+        return { value: iso, kind: 'date-time', zone: 'utc' };
+    }
+    // A named zone with no offset: keep wall time, record the TZID, do NOT convert.
+    return { value: isoSeconds(value.dateTime), kind: 'date-time', zone: 'tzid', tzid: zone };
+}
+/** Normalize one Graph event (a concrete instance from calendarView) into the model. */
+export function normalizeGraphEvent(raw, calendarId, calendarLabel) {
+    const ev = (raw ?? {});
+    const isAllDay = ev.isAllDay === true;
+    const start = graphDateTime(ev.start, isAllDay);
+    if (!start)
+        return null;
+    const id = typeof ev.id === 'string' ? ev.id : undefined;
+    const uid = typeof ev.iCalUId === 'string' && ev.iCalUId.length > 0 ? ev.iCalUId : id ?? syntheticUid('microsoft', calendarId);
+    const end = graphDateTime(ev.end, isAllDay);
+    const location = ev.location && typeof ev.location.displayName === 'string' ? ev.location.displayName : undefined;
+    return {
+        uid,
+        summary: typeof ev.subject === 'string' ? ev.subject : '(no title)',
+        ...(location ? { location } : {}),
+        ...(typeof ev.bodyPreview === 'string' && ev.bodyPreview.length > 0 ? { description: ev.bodyPreview } : {}),
+        start,
+        ...(end ? { end } : {}),
+        source: 'microsoft-graph',
+        ...(id ? { sourceEventId: id } : {}),
+        calendarId,
+        calendarLabel,
+    };
+}
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a date-time that may carry a numeric offset or trailing Z into a real
+ * UTC instant. A value with only a named zone (no offset) is impossible here (the
+ * Google API always includes an offset on dateTime), but we defend: if Date cannot
+ * parse it, keep the wall value as tzid when a zone was named, else floating.
+ */
+export function normalizeOffsetDateTime(value, namedZone) {
+    const hasOffset = /[zZ]$|[+-]\d{2}:?\d{2}$/.test(value);
+    if (hasOffset) {
+        const ms = Date.parse(value);
+        if (Number.isFinite(ms)) {
+            return { value: new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z'), kind: 'date-time', zone: 'utc' };
+        }
+    }
+    if (namedZone)
+        return { value: isoSeconds(value), kind: 'date-time', zone: 'tzid', tzid: namedZone };
+    return { value: isoSeconds(value), kind: 'date-time', zone: 'floating' };
+}
+/** Trim a provider date-time to whole-second ISO (drop sub-second + any offset tail). */
+function isoSeconds(value) {
+    const trimmed = value.replace(/\.\d+/, '');
+    const m = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})/.exec(trimmed);
+    return m ? m[1] : trimmed;
+}
+function syntheticUid(provider, calendarId) {
+    return `goodvibes-${provider}-${calendarId}-${Math.random().toString(36).slice(2, 10)}`;
+}
+// ---------------------------------------------------------------------------
+// Cross-zone chronological ordering (F4)
+// ---------------------------------------------------------------------------
+/**
+ * Best-effort epoch (ms) for one {@link EventDateTime}, for sorting a mixed list of
+ * merged events across zones/kinds. THIS IS THE ONE DOCUMENTED FUNCTION every
+ * consumer should sort through — a raw `localeCompare`/string sort on `.value` looks
+ * like it works (ISO strings are lexicographically sortable) but silently produces
+ * the wrong order the moment a `zone: 'utc'` value (a real instant) is compared
+ * against a `zone: 'tzid'` or `zone: 'floating'` value (a wall-clock reading with an
+ * unknown or undeclared offset) — e.g. a `tzid` event at `01:00` in
+ * `America/New_York` and a `utc` event at `05:00Z` are close to the same real
+ * instant (EDT is UTC-4), but a naive string/localeCompare sort of `'01:00:00'` vs
+ * `'05:00:00Z'` treats them as 4-5 hours apart on the SAME axis, which they are not.
+ *
+ * Documented approximation (this build ships no tz database, so a true conversion is
+ * not possible):
+ *  - `kind: 'date'` (all-day) => midnight UTC of that date.
+ *  - `zone: 'utc'` => the real epoch, via `Date.parse` of the (already-normalized,
+ *    Z-suffixed) ISO value. Authoritative.
+ *  - `zone: 'tzid'` or `zone: 'floating'` => the wall-clock digits are read AS IF
+ *    they were UTC (no offset applied). This is an approximation, not the true
+ *    instant — it keeps events within the SAME zone in correct relative order, and
+ *    gives cross-zone comparisons a deterministic (if approximate) answer instead of
+ *    an arbitrary one.
+ */
+export function eventDateTimeEpochMs(dt) {
+    if (dt.kind === 'date') {
+        const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(dt.value);
+        if (!m)
+            return Number.NaN;
+        return Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+    }
+    if (dt.zone === 'utc') {
+        const ms = Date.parse(dt.value);
+        if (Number.isFinite(ms))
+            return ms;
+    }
+    // tzid / floating (or an unparsable utc value, defensively): treat the wall-clock
+    // digits as if they were UTC — see the documented approximation above.
+    const m = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})/.exec(dt.value);
+    if (!m)
+        return Number.NaN;
+    return Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]), Number(m[4]), Number(m[5]), Number(m[6]));
+}
+/**
+ * Chronological comparator for {@link EventDateTime} values (ascending), suitable
+ * for `Array.prototype.sort`. See {@link eventDateTimeEpochMs} for the documented
+ * cross-zone approximation this is built on — this is the ONE function every
+ * consumer should sort through instead of inventing its own string comparison.
+ */
+export function compareEventDateTime(a, b) {
+    return eventDateTimeEpochMs(a) - eventDateTimeEpochMs(b);
+}
+/** Sort {@link MergedCalendarEvent}s by start time, through {@link compareEventDateTime}. */
+export function compareMergedCalendarEventsByStart(a, b) {
+    return compareEventDateTime(a.start, b.start);
+}

package/dist/platform/calendar/microsoft-graph-api.d.ts

@@ -0,0 +1,25 @@
+/**
+ * microsoft-graph-api.ts — the Microsoft Graph client over an access token and the
+ * injected HttpFetch. Lists calendars (me/calendars), lists events over a window
+ * (me/calendars/{id}/calendarView, which returns expanded instances), and creates
+ * events (me/calendars/{id}/events). A Prefer: outlook.timezone="UTC" header makes
+ * Graph return UTC wall times so normalization is honest. Paging follows
+ * @odata.nextLink; failures are named degraded states via CalendarApiError.
+ */
+import type { HttpFetch, MergedCalendarEvent, NewCalendarEvent, ProviderCalendar } from './oauth-types.js';
+/** List the user's calendars; write access comes from canEdit. */
+export declare function listGraphCalendars(fetchImpl: HttpFetch, token: string): Promise<ProviderCalendar[]>;
+export interface GraphEventsQuery {
+    readonly calendarId: string;
+    readonly calendarLabel: string;
+    /** ISO lower bound, e.g. '2026-07-01T00:00:00Z'. */
+    readonly start: string;
+    /** ISO upper bound. */
+    readonly end: string;
+    readonly pageSize?: number;
+}
+/** List events over a window via calendarView, paging @odata.nextLink to exhaustion. */
+export declare function listGraphEvents(fetchImpl: HttpFetch, token: string, query: GraphEventsQuery): Promise<MergedCalendarEvent[]>;
+/** Create an event; returns it normalized into the merged model. */
+export declare function createGraphEvent(fetchImpl: HttpFetch, token: string, calendarId: string, calendarLabel: string, event: NewCalendarEvent): Promise<MergedCalendarEvent>;
+//# sourceMappingURL=microsoft-graph-api.d.ts.map

package/dist/platform/calendar/microsoft-graph-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"microsoft-graph-api.d.ts","sourceRoot":"","sources":["../../../src/platform/calendar/microsoft-graph-api.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAK3G,kEAAkE;AAClE,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAsBzG;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uBAAuB;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,wFAAwF;AACxF,wBAAsB,eAAe,CACnC,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAuBhC;AAED,oEAAoE;AACpE,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,mBAAmB,CAAC,CAqB9B"}