@open-webapp/drive-sync 0.7.1 → 0.9.0

package/README.md

@@ -17,6 +17,9 @@ const drive = createDriveSync({
   appId: 'my-app',
   clientId: 'xxx.apps.googleusercontent.com',
   folderPath: ['MyApp', 'Data'],
+  // additionalScopes?: string[] — request extra OAuth scopes alongside the
+  // library's own Drive scopes. Omitted/empty = identical behavior to before
+  // this option existed.
 })
 
 const dispose = drive.activate()
@@ -38,6 +41,44 @@ const ref = await p.files.update(fileId, {
 })
 ```
 
+### Calendar events (read-only)
+
+Reuses the same connected Google account — no second OAuth flow — as long as
+`additionalScopes: ['https://www.googleapis.com/auth/calendar.readonly']` was
+passed to `createDriveSync`. The caller supplies the time window; this
+library hardcodes no date range:
+
+```ts
+const events = await p.calendar.listEvents({
+  timeMin: new Date(Date.now() - 7 * 86400_000).toISOString(),
+  timeMax: new Date(Date.now() + 30 * 86400_000).toISOString(),
+})
+```
+
+Read-only (no create/update/delete). Non-interactive by default, like
+`p.files.*` — a background poll never pops a consent screen; pass
+`{ interactive: true }` to allow one. Every event in range is returned,
+unfiltered — callers decide what to show/hide, including declined events.
+Each `CalendarEvent` includes `selfResponseStatus`, a best-effort `joinUrl`,
+and `isAllDay`-aware `start`/`end` (an all-day event has `date` set and
+`dateTime` left `undefined`).
+
+### Synchronous connection snapshot
+
+`p.getConnectionSync()` / `p.subscribeConnection()` give a framework store a
+synchronous, referentially-stable `Connection | null` without polling:
+
+```ts
+const store = {
+  get: () => p.getConnectionSync(),
+  subscribe: (onChange: () => void) => p.subscribeConnection(onChange),
+}
+```
+
+This pairing is the intended backing for `@open-webapp/drive-connect`'s React
+hook (`useDriveConnection`), and works equally well for any other
+`useSyncExternalStore`-shaped store.
+
 See `SPEC.md` for the full design: the 36 resolved decisions, storage layout,
 and refresh state machine. `SPEC.md` is descriptive, written from the shipped
 code — if it ever disagrees with the source, the source wins.

package/SPEC.md

@@ -30,6 +30,8 @@ await drive.reconcile(knownProjectIds);          // drop orphaned per-project au
 const p = drive.project(projectId);
 await p.connect();                               // interactive; prompt:'consent'
 const conn = await p.getConnection();            // { email, needsReauth, expiresAt } | null
+const snap = p.getConnectionSync();            // Connection | null, synchronous, referentially stable
+const unsub = p.subscribeConnection(() => {}); // fires when the snapshot reference changes
 
 const picked = await p.pickFile({ apiKey: PICKER_API_KEY, appId: GCP_PROJECT_NUMBER });  // file-selection via Google Picker
 const folderId = await p.ensureFolderPath();
@@ -46,10 +48,27 @@ dispose();
 
 `createDriveSync()` itself attaches no listeners and makes no network calls. Every Drive-op call site accepts an optional `{ interactive?: boolean }` (default `false`) and resolves its own token internally — no caller ever threads a token or a `projectId` string into an HTTP call by hand.
 
-Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHandle`/`PermissionsHandle`), `connection.ts` (`connect`/`getConnection`/`disconnect`/`refreshSilently`/`getAccessToken`), `files.ts`, `permissions.ts`, `reconcile.ts`, `refresh.ts` (`activate`/warm-up), `picker.ts` (Google Picker integration), `errors.ts` (typed error classes), `types.ts` (`DriveSyncOptions`, `Connection`, `StoredToken`, `FileRef`, `DrivePermission`, `CallOptions`).
+Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHandle`/`PermissionsHandle`/`CalendarHandle`, plus `getConnectionSync`/`subscribeConnection`), `connection.ts` (`connect`/`getConnection`/`disconnect`/`refreshSilently`/`getAccessToken`), `files.ts`, `permissions.ts`, `calendar.ts` (read-only Calendar events — see §2a), `reconcile.ts`, `refresh.ts` (`activate`/warm-up), `picker.ts` (Google Picker integration), `errors.ts` (typed error classes), `types.ts` (`DriveSyncOptions` incl. `additionalScopes`, `Connection`, `StoredToken`, `FileRef`, `DrivePermission`, `CallOptions`, `CalendarEvent`, `CalendarEventDateTime`, `ListEventsOptions`).
 
 `getAccessToken()` is the one deliberate exception to `Connection` never exposing secret material (types.ts): it exists solely so an app can feed the token to Google Picker (`setOAuthToken()`), which runs outside this library's control and has no other way to read it. Reuses a cached token while it has more than 5 minutes left; otherwise acquires one (interactive by default, since callers use this to drive a UI the user is actively interacting with).
 
+### Connection snapshot
+
+`index.ts` holds one in-memory `Connection | null` per `projectId`, in a `snapshotStores` Map inside the `createDriveSync` closure (alongside `trackedProjectIds`) — one `ConnectionSnapshotStore` (`connectionSnapshot.ts`) per project, created lazily on first access. Each store shallow-compares the incoming `Connection` on `email`/`needsReauth`/`expiresAt` before replacing its held reference, so `get()` returns a referentially-stable value suitable for `useSyncExternalStore`.
+
+`null` from `getConnectionSync()` is ambiguous by design: it means either "disconnected" or "not yet hydrated" (the first background re-read from IndexedDB hasn't resolved). Callers cannot distinguish the two from the return value alone.
+
+The snapshot is (re-)read from IndexedDB via `getConnection()` in several places, all but one of them fire-and-forget:
+
+- **Lazily, on first access** — the first call to `getConnectionSync()` or `subscribeConnection()` for a project kicks off a `void`-ed re-read.
+- **On a background warm-up** — `refresh.ts`'s `warmUpIfNeeded`, run from `activate()`'s `visibilitychange`/`pageshow` handlers.
+- **On a cross-tab `logout`/`token` broadcast** — `handleBroadcast` re-reads the snapshot for the affected project. This only fires while `activate()` has been called (broadcast listening starts there).
+- **For every tracked project, at `activate()` itself** — so already-registered projects get an immediate re-read when activation starts.
+
+**The one exception:** after `connect()`/`disconnect()`, the re-read is `await`ed *before* the call resolves. This is the one place callers can rely on synchronous-after-await freshness — the moment `await p.connect()` (or `disconnect()`) returns, `p.getConnectionSync()` already reflects the new state. Every other re-read above is intentionally fire-and-forget, since nothing is awaiting them to observe the snapshot synchronously.
+
+One behavioral consequence worth calling out: because the broadcast handler re-reads on `logout`, a `disconnect()` in one tab becomes observable to `subscribeConnection()` listeners in every other open tab — a capability the async-only `getConnection()` never had (nothing pushes to it).
+
 ## 2. The 41 resolved design decisions
 
 **Bugs fixed (both source apps carried these):**
@@ -109,6 +128,43 @@ Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHand
 
 42. **`list()` passes through `thumbnailLink` + `imageMediaMetadata`, unfiltered and verbatim** — `files.ts`'s `list()` extends the same `fields` mask touched in #36's `modifiedTime` change to also request `thumbnailLink` and `imageMediaMetadata(width,height,rotation)`; `FileRef` (`types.ts`) gains three optional fields — `mimeType?` (already fetched, previously just untyped), `thumbnailLink?`, and `imageMediaMetadata?: { width?; height?; rotation? }` — all `fields`-gated and may be absent on older or partial responses. `list()` stays unfiltered: it returns every file of any MIME type with no `image/` check and no opt-in flag, and `thumbnailLink` is passed through exactly as Drive returns it — no blob fetch, no URL rewrite, no `=s220` size munging, and no `files.thumbnail()` helper. Caveat: `thumbnailLink` is a short-lived URL (good for only ~hours) that can require the browser to be carrying Google auth context for the file's owning account, so a cross-origin bare `<img src>` may 403; rendering is the consuming app's responsibility, and it can fall back to `getAccessToken()` + fetch-to-blob itself. (Label is `42` though this is only the 41st entry — the section carries a duplicate `7.` label and a merged `25–27.` entry, so the labels have always run one ahead of the item count; no existing entry is renumbered.)
 
+43. **Synchronous connection snapshot, per project** — `index.ts`'s `ProjectHandle` gains `getConnectionSync(): Connection | null` and `subscribeConnection(cb): () => void`, backed by a new `connectionSnapshot.ts` (`createConnectionSnapshotStore`) held per `projectId` in the `snapshotStores` Map alongside `trackedProjectIds`. The store shallow-compares `email`/`needsReauth`/`expiresAt` so its reference stays stable across no-op re-reads (`useSyncExternalStore`-friendly). It is populated lazily on first access, kept warm by the same warm-up/broadcast/`activate()` paths that already existed, and — the one synchronous-after-await guarantee in the package — re-read and `await`ed to completion inside `connect()`/`disconnect()` before those calls resolve. A side effect: cross-tab `logout` broadcasts now push a visible state change to `subscribeConnection()` listeners, which the async-only `getConnection()` never did.
+
+## 2a. Configurable scopes and read-only Calendar events (v0.9.0)
+
+**`additionalScopes` option.** `DriveSyncOptions.additionalScopes?: string[]` (`types.ts`) lets a consumer request extra OAuth scopes alongside the library's own Drive scopes (`REQUIRED_SCOPES` — `drive.file` + `userinfo.email`, `files.ts`). `createDriveSync` computes `EFFECTIVE_SCOPES = [...REQUIRED_SCOPES, ...(options.additionalScopes ?? [])]` once, and threads that single array into every scope-consuming call site: `connect()`, `getConnection()`, `getAccessToken()`, `pickFile()`, the connection-snapshot re-read, `refresh.ts`'s `warmUpIfNeeded` (via a new `scopes` field on `ActivateOptions`), and every `files.ts`/`permissions.ts` call (via a new `requiredScopes: string[]` field on their shared `BaseCallOptions`, populated from `index.ts`'s per-project `base` object). **Backward compatibility guarantee:** when `additionalScopes` is omitted or empty, `EFFECTIVE_SCOPES` is referentially the same value set as the old bare `REQUIRED_SCOPES` constant, so every request this library makes is byte-identical to before this option existed. `connection.ts`'s existing scope-coverage check (`needsReauth`, §"resolved decisions" #19-ish / `connection.ts:233`) means a token missing a newly-added scope is genuinely treated as needing reauth, not silently ignored.
+
+**Calendar capability.** `ProjectHandle.calendar.listEvents({ timeMin, timeMax }, callOpts?)` (new `calendar.ts`, wired onto `ProjectHandle` in `index.ts` alongside `files`/`permissions`, sharing the same per-project `base` object and therefore the same `EFFECTIVE_SCOPES`) issues `GET https://www.googleapis.com/calendar/v3/calendars/primary/events?timeMin=...&timeMax=...&singleEvents=true&orderBy=startTime` through the same `driveFetch` (`http.ts`) every Drive call uses — `driveFetch` is generic over the request URL/host and only hardcodes Drive-specific behavior in its error-message text, so it needed no changes to serve a non-Drive Google API. The library hardcodes no date range; the caller supplies `timeMin`/`timeMax` as ISO 8601 strings. Read-only: no create/update/delete Calendar operation exists in this package. Every event Google returns in range is mapped and returned unfiltered, in Google's own `orderBy: startTime` order — no RSVP filtering or declined-event dropping happens in the library; that is an app-side decision.
+
+Like every `files.*`/`permissions.*` call, `listEvents` defaults `interactive` to `false` (NOT `getAccessToken()`'s interactive-by-default exception) — a background calendar poll never triggers a consent popup. Pass `{ interactive: true }` to allow one.
+
+**Normalized `CalendarEvent` shape** (`types.ts`):
+
+```ts
+interface CalendarEventDateTime {
+  dateTime?: string; // present for timed events
+  date?: string;     // present for all-day events (YYYY-MM-DD), mutually exclusive with dateTime
+  timeZone?: string;
+}
+interface CalendarEvent {
+  id: string;
+  summary: string;
+  start: CalendarEventDateTime;
+  end: CalendarEventDateTime;
+  isAllDay: boolean; // true iff start.date is present with no start.dateTime
+  selfResponseStatus: 'accepted' | 'tentative' | 'needsAction' | 'declined';
+  joinUrl: string | null;
+  organizer: { displayName?: string; email?: string; self: boolean };
+  htmlLink: string;
+}
+```
+
+**`selfResponseStatus` derivation** (`calendar.ts`'s `deriveSelfResponseStatus`): if the raw event has an `attendees` array, find the entry with `self === true` and pass its `responseStatus` through verbatim (Google's enum already matches this type; defaults to `'needsAction'` if a non-empty `attendees` array somehow has no self entry). If there is no `attendees` array at all (a self-only event, or an organizer with nothing to respond to), the status is `'accepted'`.
+
+**`joinUrl` derivation** (`calendar.ts`'s `extractJoinUrl`), in precedence order: (1) `event.hangoutLink` if present; (2) the first `event.conferenceData.entryPoints` entry with `entryPointType === 'video'`, its `uri`; (3) a best-effort regex scan, `event.location` then `event.description`, for the first URL matching `zoom.us`, `meet.google.com`, or `teams.microsoft.com` (may false-negative on oddly formatted text — accepted, since the two structured sources above cover the common case); (4) `null` if nothing matches.
+
+**All-day events.** `isAllDay = Boolean(raw.start?.date && !raw.start?.dateTime)`. The mapper (`calendar.ts`'s `mapEvent`) reads `start.date`/`end.date` when present and never assumes `start.dateTime` exists — an all-day event's `dateTime` field stays `undefined` on the normalized `CalendarEvent`, it is never coerced to `''` or allowed to throw.
+
 ## 3. Storage layout
 
 Each project gets its own IndexedDB database: **`owa-drive-{appId}-{projectId}`**, version 1, containing one object store, `auth` (`storage.ts`). The store holds up to three keys (`conn`/`token` always; `envelope` only in server-facilitated token-exchange mode):

package/dist/calendar.d.ts

@@ -0,0 +1,58 @@
+import type { Logger } from './logger.js';
+import type { CalendarEvent, ListEventsOptions } from './types.js';
+interface RawGoogleCalendarEventDateTime {
+    dateTime?: string;
+    date?: string;
+    timeZone?: string;
+}
+interface RawGoogleCalendarEvent {
+    id: string;
+    summary?: string;
+    start?: RawGoogleCalendarEventDateTime;
+    end?: RawGoogleCalendarEventDateTime;
+    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: RawGoogleCalendarEvent): CalendarEvent['selfResponseStatus'];
+export declare function extractJoinUrl(raw: RawGoogleCalendarEvent): string | null;
+export declare function mapEvent(raw: RawGoogleCalendarEvent): CalendarEvent;
+export interface ListEventsCallOptions extends ListEventsOptions {
+    appId: string;
+    projectId: string;
+    clientId: string;
+    interactive?: boolean;
+    logger?: Logger;
+    fetchEmail?: (accessToken: string) => Promise<string>;
+    tokenExchangeUrl?: string;
+    requiredScopes: string[];
+}
+/**
+ * Read-only listing of the connected account's primary calendar events in
+ * `[timeMin, timeMax)`. Reuses `driveFetch` (generic enough for any Google
+ * API host, not Drive-specific — it only hardcodes Drive-specific behavior
+ * in its error-message text, not its request path) for the same
+ * token-acquisition / retry / 401-recovery plumbing `files.ts` uses.
+ *
+ * Non-interactive by default (like `files.*`, NOT `getAccessToken`'s
+ * interactive-by-default exception) so a background poll never pops a
+ * consent screen.
+ */
+export declare function listEvents(opts: ListEventsCallOptions): Promise<CalendarEvent[]>;
+export {};

package/dist/calendar.js

@@ -0,0 +1,84 @@
+import { driveFetch } from './http.js';
+const CALENDAR_BASE = 'https://www.googleapis.com/calendar/v3';
+/**
+ * Best-effort scan for a meeting link in free-text fields. May false-negative
+ * on oddly formatted text — acceptable, since `hangoutLink`/`conferenceData`
+ * (checked first, in `extractJoinUrl`) cover the common case.
+ */
+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 self = raw.attendees.find((a) => a.self === true);
+    const status = self?.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 videoEntryPoint = raw.conferenceData?.entryPoints?.find((ep) => ep.entryPointType === 'video');
+    if (videoEntryPoint?.uri) {
+        return videoEntryPoint.uri;
+    }
+    const locationMatch = raw.location?.match(JOIN_URL_REGEX);
+    if (locationMatch) {
+        return locationMatch[0];
+    }
+    const descriptionMatch = raw.description?.match(JOIN_URL_REGEX);
+    if (descriptionMatch) {
+        return descriptionMatch[0];
+    }
+    return null;
+}
+export function mapEvent(raw) {
+    const start = raw.start ?? {};
+    const end = raw.end ?? {};
+    return {
+        id: raw.id,
+        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,
+    };
+}
+/**
+ * Read-only listing of the connected account's primary calendar events in
+ * `[timeMin, timeMax)`. Reuses `driveFetch` (generic enough for any Google
+ * API host, not Drive-specific — it only hardcodes Drive-specific behavior
+ * in its error-message text, not its request path) for the same
+ * token-acquisition / retry / 401-recovery plumbing `files.ts` uses.
+ *
+ * Non-interactive by default (like `files.*`, NOT `getAccessToken`'s
+ * interactive-by-default exception) so a background poll never pops a
+ * consent screen.
+ */
+export async function listEvents(opts) {
+    const url = `${CALENDAR_BASE}/calendars/primary/events?timeMin=${encodeURIComponent(opts.timeMin)}&timeMax=${encodeURIComponent(opts.timeMax)}&singleEvents=true&orderBy=startTime`;
+    const res = await driveFetch({
+        appId: opts.appId,
+        projectId: opts.projectId,
+        clientId: opts.clientId,
+        url,
+        method: 'GET',
+        interactive: opts.interactive ?? false,
+        requiredScopes: opts.requiredScopes,
+        logger: opts.logger,
+        fetchEmail: opts.fetchEmail,
+        tokenExchangeUrl: opts.tokenExchangeUrl,
+    });
+    const json = (await res.json());
+    return (json.items ?? []).map(mapEvent);
+}

package/dist/connectionSnapshot.d.ts

@@ -0,0 +1,17 @@
+import type { Connection } from './types.js';
+export interface ConnectionSnapshotStore {
+    get(): Connection | null;
+    commit(next: Connection | null): void;
+    subscribe(fn: () => void): () => void;
+}
+/**
+ * Tiny non-React store suitable for use with useSyncExternalStore, holding
+ * the durable Connection snapshot (or null when disconnected).
+ *
+ * - `get()` returns a stable reference; the internal snapshot is only
+ *   replaced when at least one of the 3 fields differs (shallow compare).
+ * - `commit` notifies listeners only when the snapshot reference changed.
+ * - `subscribe` returns an unsubscribe fn; unsubscribing during a notify
+ *   pass is safe (listeners are iterated over a copy).
+ */
+export declare function createConnectionSnapshotStore(): ConnectionSnapshotStore;

package/dist/connectionSnapshot.js

@@ -0,0 +1,48 @@
+function shallowEqualConn(a, b) {
+    if (a === null && b === null)
+        return true;
+    if (a === null || b === null)
+        return false;
+    return (a.email === b.email &&
+        a.needsReauth === b.needsReauth &&
+        a.expiresAt === b.expiresAt);
+}
+/**
+ * Tiny non-React store suitable for use with useSyncExternalStore, holding
+ * the durable Connection snapshot (or null when disconnected).
+ *
+ * - `get()` returns a stable reference; the internal snapshot is only
+ *   replaced when at least one of the 3 fields differs (shallow compare).
+ * - `commit` notifies listeners only when the snapshot reference changed.
+ * - `subscribe` returns an unsubscribe fn; unsubscribing during a notify
+ *   pass is safe (listeners are iterated over a copy).
+ */
+export function createConnectionSnapshotStore() {
+    let snapshot = null;
+    const listeners = new Set();
+    function notify() {
+        for (const fn of [...listeners]) {
+            fn();
+        }
+    }
+    function commit(next) {
+        if (shallowEqualConn(snapshot, next))
+            return;
+        snapshot = next;
+        notify();
+    }
+    return {
+        get() {
+            return snapshot;
+        },
+        commit(next) {
+            commit(next);
+        },
+        subscribe(fn) {
+            listeners.add(fn);
+            return () => {
+                listeners.delete(fn);
+            };
+        },
+    };
+}

package/dist/files.d.ts

@@ -15,6 +15,11 @@ interface BaseCallOptions {
      * through `refreshEnvelope` (see http.ts). Absent for the legacy GIS path.
      */
     tokenExchangeUrl?: string;
+    /**
+     * Scopes required for this call, threaded in by index.ts as the caller's
+     * effective scope set (`REQUIRED_SCOPES` plus any `additionalScopes`).
+     */
+    requiredScopes: string[];
 }
 export interface ReadOptions extends BaseCallOptions {
     fileId: string;

package/dist/files.js

@@ -23,7 +23,7 @@ async function fetchRemoteVersion(opts) {
             url: `${DRIVE_BASE}/files/${encodeURIComponent(opts.fileId)}?fields=${encodeURIComponent('id,name,version,modifiedTime')}`,
             method: 'GET',
             interactive: opts.interactive,
-            requiredScopes: REQUIRED_SCOPES,
+            requiredScopes: opts.requiredScopes,
             logger: opts.logger,
             fetchEmail: opts.fetchEmail,
             tokenExchangeUrl: opts.tokenExchangeUrl,
@@ -74,7 +74,7 @@ export async function read(opts) {
             url: `${DRIVE_BASE}/files/${encodeURIComponent(opts.fileId)}?alt=media`,
             method: 'GET',
             interactive: opts.interactive,
-            requiredScopes: REQUIRED_SCOPES,
+            requiredScopes: opts.requiredScopes,
             logger: opts.logger,
             fetchEmail: opts.fetchEmail,
             tokenExchangeUrl: opts.tokenExchangeUrl,
@@ -106,7 +106,7 @@ export async function remove(opts) {
         url: `${DRIVE_BASE}/files/${encodeURIComponent(opts.fileId)}`,
         method: 'DELETE',
         interactive: opts.interactive,
-        requiredScopes: REQUIRED_SCOPES,
+        requiredScopes: opts.requiredScopes,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
         tokenExchangeUrl: opts.tokenExchangeUrl,
@@ -159,7 +159,7 @@ async function updateContent(opts, fileId, knownRemoteVersion) {
         headers: { 'Content-Type': opts.mimeType },
         body: opts.content,
         interactive: opts.interactive,
-        requiredScopes: REQUIRED_SCOPES,
+        requiredScopes: opts.requiredScopes,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
         tokenExchangeUrl: opts.tokenExchangeUrl,
@@ -204,6 +204,7 @@ export async function write(opts) {
             logger: opts.logger,
             fetchEmail: opts.fetchEmail,
             tokenExchangeUrl: opts.tokenExchangeUrl,
+            requiredScopes: opts.requiredScopes,
         });
         if (existing.length > 0) {
             return updateContent(opts, existing[0].id, existing[0].version);
@@ -243,7 +244,7 @@ export async function write(opts) {
         headers: multipartContentType ? { 'Content-Type': multipartContentType } : undefined,
         body: multipartBody,
         interactive: opts.interactive,
-        requiredScopes: REQUIRED_SCOPES,
+        requiredScopes: opts.requiredScopes,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
         tokenExchangeUrl: opts.tokenExchangeUrl,
@@ -319,7 +320,7 @@ export async function list(opts) {
         url,
         method: 'GET',
         interactive: opts.interactive,
-        requiredScopes: REQUIRED_SCOPES,
+        requiredScopes: opts.requiredScopes,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
         tokenExchangeUrl: opts.tokenExchangeUrl,
@@ -345,7 +346,7 @@ async function createFolder(opts) {
             parents: opts.parentId ? [opts.parentId] : undefined,
         }),
         interactive: opts.interactive,
-        requiredScopes: REQUIRED_SCOPES,
+        requiredScopes: opts.requiredScopes,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
         tokenExchangeUrl: opts.tokenExchangeUrl,
@@ -380,6 +381,7 @@ export async function ensureFolderPath(opts) {
             logger: opts.logger,
             fetchEmail: opts.fetchEmail,
             tokenExchangeUrl: opts.tokenExchangeUrl,
+            requiredScopes: opts.requiredScopes,
             folderId: parentId,
             mimeType: FOLDER_MIME_TYPE,
             nameEquals: name,
@@ -396,6 +398,7 @@ export async function ensureFolderPath(opts) {
             logger: opts.logger,
             fetchEmail: opts.fetchEmail,
             tokenExchangeUrl: opts.tokenExchangeUrl,
+            requiredScopes: opts.requiredScopes,
             name,
             parentId,
         });

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import type { CallOptions, Connection, DriveSyncOptions, DrivePermission, FileRef, FileState, PickFileOptions, PickedFile } from './types.js';
-export type { DriveSyncOptions, Connection, StoredToken, FileRef, FileState, DrivePermission, CallOptions, WorkspaceMimeShorthand, PickFileOptions, PickedFile, Envelope, EnvelopePayload } from './types.js';
+import type { CallOptions, CalendarEvent, Connection, DriveSyncOptions, DrivePermission, FileRef, FileState, ListEventsOptions, PickFileOptions, PickedFile } from './types.js';
+export type { DriveSyncOptions, Connection, StoredToken, FileRef, FileState, DrivePermission, CallOptions, WorkspaceMimeShorthand, PickFileOptions, PickedFile, Envelope, EnvelopePayload, CalendarEvent, CalendarEventDateTime, ListEventsOptions } from './types.js';
 export * from './errors.js';
 export interface FilesHandle {
     list(opts?: {
@@ -44,6 +44,9 @@ export interface PermissionsHandle {
         permissionId: string;
     }, callOpts?: CallOptions): Promise<void>;
 }
+export interface CalendarHandle {
+    listEvents(opts: ListEventsOptions, callOpts?: CallOptions): Promise<CalendarEvent[]>;
+}
 export interface ProjectHandle {
     connect(): Promise<Connection>;
     getConnection(): Promise<Connection | null>;
@@ -58,8 +61,23 @@ export interface ProjectHandle {
      */
     getAccessToken(callOpts?: CallOptions): Promise<string>;
     pickFile(options: PickFileOptions): Promise<PickedFile[]>;
+    /**
+     * Synchronous snapshot of the current Connection, backed by the
+     * per-project connectionSnapshot store (see connectionSnapshot.ts).
+     * Never returns a Promise and never throws. `null` means either
+     * disconnected, or not-yet-hydrated (the first background re-read from
+     * IndexedDB hasn't resolved yet) — callers cannot distinguish the two
+     * from this alone.
+     */
+    getConnectionSync(): Connection | null;
+    /**
+     * Subscribes to changes in the synchronous Connection snapshot (suitable
+     * for `useSyncExternalStore`). Returns an unsubscribe function.
+     */
+    subscribeConnection(cb: () => void): () => void;
     files: FilesHandle;
     permissions: PermissionsHandle;
+    calendar: CalendarHandle;
 }
 export interface DriveSync {
     activate(): () => void;

package/dist/index.js

@@ -4,8 +4,10 @@ import { reconcile as reconcileImpl, dropProject as dropProjectImpl } from './re
 import * as filesImpl from './files.js';
 import * as permissionsImpl from './permissions.js';
 import * as pickerImpl from './picker.js';
+import * as calendarImpl from './calendar.js';
 import { warmUpIfNeeded } from './refresh.js';
 import { REQUIRED_SCOPES } from './files.js';
+import { createConnectionSnapshotStore } from './connectionSnapshot.js';
 import { createBroadcast } from './broadcast.js';
 import { evictDbHandle } from './storage.js';
 import { notifyExternalTokenRefresh } from './token.js';
@@ -49,6 +51,12 @@ async function revokeToken(accessToken) {
 export function createDriveSync(options) {
     const { appId, clientId, folderPath, tokenExchangeUrl } = options;
     const logger = options.logger ?? noOpLogger;
+    /**
+     * Base Drive scopes plus any caller-requested extras (e.g.
+     * `calendar.readonly`). Omitted `additionalScopes` -> identical to
+     * `REQUIRED_SCOPES` alone, so a consumer that never sets it is unaffected.
+     */
+    const EFFECTIVE_SCOPES = [...REQUIRED_SCOPES, ...(options.additionalScopes ?? [])];
     /**
      * Design choice for `.activate()` (T30): the frozen public API's
      * `activate()` takes no project argument, but the actual background
@@ -68,6 +76,43 @@ export function createDriveSync(options) {
     function trackProject(projectId) {
         trackedProjectIds.add(projectId);
     }
+    /**
+     * Per-project synchronous Connection snapshot stores (see
+     * connectionSnapshot.ts). Populated lazily by `getOrInitStore` the first
+     * time either `getConnectionSync()` or `subscribeConnection()` is called
+     * for a given project; a later task (T3) will also commit into these
+     * stores after connect()/disconnect() resolve.
+     */
+    const snapshotStores = new Map();
+    /**
+     * Re-reads the durable Connection for `projectId` from IndexedDB (via
+     * connection.ts's `getConnection`) and commits the result into that
+     * project's snapshot store. Returns the underlying promise (rather than
+     * `void`-ing it here) so a LATER task (T3) can `await` it after
+     * connect()/disconnect(); call sites in THIS task fire it with `void`.
+     */
+    function reReadConnection(projectId) {
+        return getConnectionImpl({
+            appId,
+            projectId,
+            requiredScopes: EFFECTIVE_SCOPES,
+        })
+            .then((conn) => {
+            getOrInitStore(projectId).commit(conn);
+        })
+            .catch((err) => {
+            logger.warn('drive-sync: connection snapshot re-read failed', { err });
+        });
+    }
+    function getOrInitStore(projectId) {
+        let store = snapshotStores.get(projectId);
+        if (!store) {
+            store = createConnectionSnapshotStore();
+            snapshotStores.set(projectId, store);
+            void reReadConnection(projectId);
+        }
+        return store;
+    }
     /**
      * Handles a cross-tab broadcast (see broadcast.ts) received while active.
      * `logout`: another tab's disconnect() already cleared BOTH IndexedDB
@@ -87,19 +132,23 @@ export function createDriveSync(options) {
     function handleBroadcast(msg) {
         if (msg.type === 'logout') {
             void evictDbHandle(appId, msg.projectId);
+            reReadConnection(msg.projectId);
         }
         else if (msg.type === 'token') {
             notifyExternalTokenRefresh(msg.projectId);
+            reReadConnection(msg.projectId);
         }
     }
     function activate() {
         const disposeBroadcast = createBroadcast(appId).onMessage(handleBroadcast);
+        for (const projectId of trackedProjectIds)
+            reReadConnection(projectId);
         if (typeof document === 'undefined') {
             return disposeBroadcast;
         }
         const runWarmUps = () => {
             for (const projectId of trackedProjectIds) {
-                void warmUpIfNeeded({ appId, projectId, clientId, tokenExchangeUrl, fetchEmail, logger });
+                void warmUpIfNeeded({ appId, projectId, clientId, scopes: EFFECTIVE_SCOPES, tokenExchangeUrl, fetchEmail, logger }).then(() => reReadConnection(projectId), () => reReadConnection(projectId));
             }
         };
         const onVisibilityChange = () => {
@@ -131,7 +180,7 @@ export function createDriveSync(options) {
     }
     function project(projectId) {
         trackProject(projectId);
-        const base = { appId, projectId, clientId, tokenExchangeUrl, logger, fetchEmail };
+        const base = { appId, projectId, clientId, tokenExchangeUrl, logger, fetchEmail, requiredScopes: EFFECTIVE_SCOPES };
         const files = {
             list(opts, callOpts) {
                 return filesImpl.list({ ...base, ...opts, interactive: callOpts?.interactive });
@@ -163,23 +212,37 @@ export function createDriveSync(options) {
                 return permissionsImpl.revoke({ ...base, ...opts, interactive: callOpts?.interactive });
             },
         };
+        const calendar = {
+            listEvents(opts, callOpts) {
+                return calendarImpl.listEvents({ ...base, ...opts, interactive: callOpts?.interactive });
+            },
+        };
         return {
-            connect() {
-                return connectImpl({
+            async connect() {
+                const connection = await connectImpl({
                     appId,
                     projectId,
                     clientId,
-                    scopes: REQUIRED_SCOPES,
+                    scopes: EFFECTIVE_SCOPES,
                     tokenExchangeUrl,
                     logger,
                     fetchEmail,
                 });
+                // Awaited (not fire-and-forget): callers of `await connect()` must
+                // see `getConnectionSync()` already reflect this new connection the
+                // moment the promise settles — see reReadConnection's docstring.
+                // Contrast with warm-up/broadcast/lazy-kick re-reads elsewhere in
+                // this file, which are intentionally fire-and-forget (`void
+                // reReadConnection(...)`) since nothing is awaiting them to observe
+                // the snapshot synchronously.
+                await reReadConnection(projectId);
+                return connection;
             },
             getConnection() {
                 return getConnectionImpl({
                     appId,
                     projectId,
-                    requiredScopes: REQUIRED_SCOPES,
+                    requiredScopes: EFFECTIVE_SCOPES,
                 });
             },
             async disconnect() {
@@ -201,6 +264,10 @@ export function createDriveSync(options) {
                     },
                 };
                 await disconnectImpl(disconnectOpts);
+                // Awaited, same reasoning as connect() above: `await disconnect()`
+                // must not settle until `getConnectionSync()` reflects the
+                // post-disconnect snapshot.
+                await reReadConnection(projectId);
             },
             ensureFolderPath() {
                 return filesImpl.ensureFolderPath({ ...base, folderPath });
@@ -210,7 +277,7 @@ export function createDriveSync(options) {
                     appId,
                     projectId,
                     clientId,
-                    scopes: REQUIRED_SCOPES,
+                    scopes: EFFECTIVE_SCOPES,
                     interactive: callOpts?.interactive ?? true,
                     tokenExchangeUrl,
                     logger,
@@ -221,7 +288,7 @@ export function createDriveSync(options) {
                     appId,
                     projectId,
                     clientId,
-                    scopes: REQUIRED_SCOPES,
+                    scopes: EFFECTIVE_SCOPES,
                     interactive: true,
                     tokenExchangeUrl,
                     logger,
@@ -245,8 +312,15 @@ export function createDriveSync(options) {
                 }
                 return results;
             },
+            getConnectionSync() {
+                return getOrInitStore(projectId).get();
+            },
+            subscribeConnection(cb) {
+                return getOrInitStore(projectId).subscribe(cb);
+            },
             files,
             permissions,
+            calendar,
         };
     }
     return {

package/dist/permissions.d.ts

@@ -13,6 +13,11 @@ interface BaseCallOptions {
      * through `refreshEnvelope` (see http.ts). Absent for the legacy GIS path.
      */
     tokenExchangeUrl?: string;
+    /**
+     * Scopes required for this call, threaded in by index.ts as the caller's
+     * effective scope set (`REQUIRED_SCOPES` plus any `additionalScopes`).
+     */
+    requiredScopes: string[];
 }
 export interface ListPermissionsOptions extends BaseCallOptions {
     fileId: string;

package/dist/permissions.js

@@ -1,5 +1,4 @@
 import { driveFetch } from './http.js';
-import { REQUIRED_SCOPES } from './files.js';
 const DRIVE_BASE = 'https://www.googleapis.com/drive/v3';
 export async function list(opts) {
     const res = await driveFetch({
@@ -9,7 +8,7 @@ export async function list(opts) {
         url: `${DRIVE_BASE}/files/${encodeURIComponent(opts.fileId)}/permissions?fields=${encodeURIComponent('permissions(id,type,role,emailAddress)')}`,
         method: 'GET',
         interactive: opts.interactive,
-        requiredScopes: REQUIRED_SCOPES,
+        requiredScopes: opts.requiredScopes,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
         tokenExchangeUrl: opts.tokenExchangeUrl,
@@ -35,7 +34,7 @@ export async function grant(opts) {
             emailAddress: opts.type === 'user' ? opts.emailAddress : undefined,
         }),
         interactive: opts.interactive,
-        requiredScopes: REQUIRED_SCOPES,
+        requiredScopes: opts.requiredScopes,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
         tokenExchangeUrl: opts.tokenExchangeUrl,
@@ -52,7 +51,7 @@ export async function update(opts) {
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ role: opts.role }),
         interactive: opts.interactive,
-        requiredScopes: REQUIRED_SCOPES,
+        requiredScopes: opts.requiredScopes,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
         tokenExchangeUrl: opts.tokenExchangeUrl,
@@ -67,7 +66,7 @@ export async function revoke(opts) {
         url: `${DRIVE_BASE}/files/${encodeURIComponent(opts.fileId)}/permissions/${encodeURIComponent(opts.permissionId)}`,
         method: 'DELETE',
         interactive: opts.interactive,
-        requiredScopes: REQUIRED_SCOPES,
+        requiredScopes: opts.requiredScopes,
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
         tokenExchangeUrl: opts.tokenExchangeUrl,

package/dist/refresh.d.ts

@@ -4,6 +4,8 @@ export interface ActivateOptions {
     appId: string;
     projectId: string;
     clientId: string;
+    /** Effective scope set (base scopes plus any `additionalScopes`) to warm up. */
+    scopes: string[];
     /**
      * Resolves the connected account's email from a fresh access token. When
      * supplied, the warm-up's non-interactive refresh goes through

package/dist/refresh.js

@@ -2,7 +2,6 @@ import { getConnection, refreshSilently } from './connection.js';
 import { getToken } from './storage.js';
 import { acquireToken } from './token.js';
 import { refreshEnvelope } from './envelope.js';
-import { REQUIRED_SCOPES } from './files.js';
 export const REFRESH_BUFFER_MS = 5 * 60 * 1000;
 /**
  * Per-project token warm-up check: if a connection exists AND its cached
@@ -19,7 +18,7 @@ export async function warmUpIfNeeded(opts) {
         const conn = await getConnection({
             appId: opts.appId,
             projectId: opts.projectId,
-            requiredScopes: REQUIRED_SCOPES,
+            requiredScopes: opts.scopes,
         });
         if (!conn) {
             // No connection at all -> no warm-up.
@@ -43,7 +42,7 @@ export async function warmUpIfNeeded(opts) {
                 appId: opts.appId,
                 projectId: opts.projectId,
                 clientId: opts.clientId,
-                scopes: REQUIRED_SCOPES,
+                scopes: opts.scopes,
                 expectedEmail: conn.email,
                 fetchEmail: opts.fetchEmail,
                 logger: opts.logger,
@@ -54,7 +53,7 @@ export async function warmUpIfNeeded(opts) {
                 appId: opts.appId,
                 projectId: opts.projectId,
                 clientId: opts.clientId,
-                scopes: REQUIRED_SCOPES,
+                scopes: opts.scopes,
                 interactive: false,
                 hint: conn.email,
                 logger: opts.logger,

package/dist/types.d.ts

@@ -10,6 +10,11 @@ export interface DriveSyncOptions {
      * the legacy implicit flow is used unchanged.
      */
     tokenExchangeUrl?: string;
+    /**
+     * Extra OAuth scopes requested alongside the library's own Drive scopes.
+     * Empty/omitted = identical behavior to before this option existed.
+     */
+    additionalScopes?: string[];
 }
 /**
  * Decoded contents of an {@link Envelope}'s `payload`. Mirrors the fields of
@@ -122,3 +127,33 @@ export interface CallOptions {
     /** Whether an interactive (popup/redirect) auth flow may be triggered. Defaults to false. */
     interactive?: boolean;
 }
+/** A Calendar event's start/end. Exactly one of `dateTime`/`date` is present. */
+export interface CalendarEventDateTime {
+    /** Present for timed events. */
+    dateTime?: string;
+    /** Present for all-day events (YYYY-MM-DD); mutually exclusive with `dateTime`. */
+    date?: string;
+    timeZone?: string;
+}
+/** Normalized read-only representation of a Google Calendar event. */
+export interface CalendarEvent {
+    id: string;
+    summary: string;
+    start: CalendarEventDateTime;
+    end: CalendarEventDateTime;
+    /** True iff `start.date` is present with no `start.dateTime`. */
+    isAllDay: boolean;
+    selfResponseStatus: 'accepted' | 'tentative' | 'needsAction' | 'declined';
+    joinUrl: string | null;
+    organizer: {
+        displayName?: string;
+        email?: string;
+        self: boolean;
+    };
+    htmlLink: string;
+}
+/** Options for `ProjectHandle.calendar.listEvents()`. Caller supplies the time window. */
+export interface ListEventsOptions {
+    timeMin: string;
+    timeMax: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-webapp/drive-sync",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "type": "module",
   "repository": {
     "type": "git",