@open-webapp/drive-sync 0.8.0 → 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,28 @@ 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

package/SPEC.md

@@ -48,7 +48,7 @@ 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`, plus `getConnectionSync`/`subscribeConnection`), `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).
 
@@ -130,6 +130,41 @@ One behavioral consequence worth calling out: because the broadcast handler re-r
 
 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/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>;
@@ -74,6 +77,7 @@ export interface ProjectHandle {
     subscribeConnection(cb: () => void): () => void;
     files: FilesHandle;
     permissions: PermissionsHandle;
+    calendar: CalendarHandle;
 }
 export interface DriveSync {
     activate(): () => void;

package/dist/index.js

@@ -4,6 +4,7 @@ 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';
@@ -50,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
@@ -88,7 +95,7 @@ export function createDriveSync(options) {
         return getConnectionImpl({
             appId,
             projectId,
-            requiredScopes: REQUIRED_SCOPES,
+            requiredScopes: EFFECTIVE_SCOPES,
         })
             .then((conn) => {
             getOrInitStore(projectId).commit(conn);
@@ -141,7 +148,7 @@ export function createDriveSync(options) {
         }
         const runWarmUps = () => {
             for (const projectId of trackedProjectIds) {
-                void warmUpIfNeeded({ appId, projectId, clientId, tokenExchangeUrl, fetchEmail, logger }).then(() => reReadConnection(projectId), () => reReadConnection(projectId));
+                void warmUpIfNeeded({ appId, projectId, clientId, scopes: EFFECTIVE_SCOPES, tokenExchangeUrl, fetchEmail, logger }).then(() => reReadConnection(projectId), () => reReadConnection(projectId));
             }
         };
         const onVisibilityChange = () => {
@@ -173,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 });
@@ -205,13 +212,18 @@ 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 {
             async connect() {
                 const connection = await connectImpl({
                     appId,
                     projectId,
                     clientId,
-                    scopes: REQUIRED_SCOPES,
+                    scopes: EFFECTIVE_SCOPES,
                     tokenExchangeUrl,
                     logger,
                     fetchEmail,
@@ -230,7 +242,7 @@ export function createDriveSync(options) {
                 return getConnectionImpl({
                     appId,
                     projectId,
-                    requiredScopes: REQUIRED_SCOPES,
+                    requiredScopes: EFFECTIVE_SCOPES,
                 });
             },
             async disconnect() {
@@ -265,7 +277,7 @@ export function createDriveSync(options) {
                     appId,
                     projectId,
                     clientId,
-                    scopes: REQUIRED_SCOPES,
+                    scopes: EFFECTIVE_SCOPES,
                     interactive: callOpts?.interactive ?? true,
                     tokenExchangeUrl,
                     logger,
@@ -276,7 +288,7 @@ export function createDriveSync(options) {
                     appId,
                     projectId,
                     clientId,
-                    scopes: REQUIRED_SCOPES,
+                    scopes: EFFECTIVE_SCOPES,
                     interactive: true,
                     tokenExchangeUrl,
                     logger,
@@ -308,6 +320,7 @@ export function createDriveSync(options) {
             },
             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.8.0",
+  "version": "0.9.0",
   "type": "module",
   "repository": {
     "type": "git",