@open-webapp/drive-sync 0.2.0 → 0.3.0

package/README.md

@@ -24,6 +24,7 @@ await drive.reconcile(knownProjectIds)
 
 const p = drive.project(projectId)
 await p.connect()
+const picked = await p.pickFile({ apiKey: PICKER_API_KEY, appId: GCP_PROJECT_NUMBER })
 const folderId = await p.ensureFolderPath()
 await p.files.write({ folderId, name: 'data.json', content: '{}', mimeType: 'application/json' })
 ```

package/SPEC.md

@@ -31,8 +31,9 @@ const p = drive.project(projectId);
 await p.connect();                               // interactive; prompt:'consent'
 const conn = await p.getConnection();            // { email, needsReauth, expiresAt } | null
 
+const picked = await p.pickFile({ apiKey: PICKER_API_KEY, appId: GCP_PROJECT_NUMBER });  // file-selection via Google Picker
 const folderId = await p.ensureFolderPath();
-const token = await p.getAccessToken();          // raw token, for Google Picker's setOAuthToken() only
+const token = await p.getAccessToken();          // raw token for advanced/custom Picker wiring; pickFile() is the preferred path for most uses
 const files = await p.files.list({ folderId });
 const text = await p.files.read(fileId);         // string | Blob | null (null on 404)
 const ref = await p.files.write({ folderId, name: 'x.json', content, mimeType: 'application/json' });
@@ -45,11 +46,11 @@ 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), `errors.ts` (typed error classes), `types.ts` (`DriveSyncOptions`, `Connection`, `StoredToken`, `FileRef`, `DrivePermission`, `CallOptions`).
+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`).
 
 `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).
 
-## 2. The 34 resolved design decisions
+## 2. The 35 resolved design decisions
 
 **Bugs fixed (both source apps carried these):**
 
@@ -91,6 +92,7 @@ Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHand
 32. **`reconcile`/`dropProject`** — `reconcile.ts`: `reconcile(appId, knownProjectIds)` enumerates via `indexedDB.databases()` and deletes any `owa-drive-{appId}-*` DB not in the known set; `dropProject(appId, projectId)` deletes one DB eagerly and evicts its cached handle.
 33. **No timer; warm-up on `visibilitychange`/`pageshow`** — `refresh.ts`'s `activate()` attaches both listeners (only when called; none at import time), gated on `document.visibilityState === 'visible'` / `event.persisted && !document.hidden`; `warmUpIfNeeded` only fires if a connection exists **and** the token is missing or within a 5-minute buffer (`REFRESH_BUFFER_MS`) of expiry. `index.ts`'s top-level `activate()` also layers a `trackedProjectIds` Set so one global listener pair drives warm-ups for every project ever passed to `.project(id)`.
 34. **`interactive` option, default `false`** — every `BaseCallOptions`-shaped call in `files.ts`/`permissions.ts`/`http.ts` defaults `interactive` to falsy; a non-interactive call with no usable token throws `NeedsReauthError` rather than silently prompting.
+35. **Google Picker integration** — `picker.ts`'s `pickFile` accepts an `apiKey` and an `appId` (the OAuth client's Cloud project number) per-call (not stored in `DriveSyncOptions`); `appId` is mandatory because drive-sync holds only a `drive.file`-scoped token and Picker rejects a scoped session it cannot attribute to an app — omitting it makes Picker drop the OAuth token, show its own sign-in prompt, and fail with "The API developer key is invalid"; `index.ts` and `connection.ts` resolve the token, but `picker.ts` only ever sees a plain string token to avoid secret exposure. Script loading is cached at module level to avoid repeated GIS-loader calls. On user cancel, `PickerCancelledError` is thrown; on success, `FileRef` is returned. Drive scope prerequisites and token refresh are handled transparently (`picker.ts` takes the token and makes the Picker call; no token-boundary complexity leaks to callers).
 
 ## 3. Storage layout
 

package/dist/errors.d.ts

@@ -58,7 +58,35 @@ export declare class RateLimitedError extends DriveSyncError {
 export declare class TransientError extends DriveSyncError {
     constructor(message?: string, opts?: DriveSyncErrorOptions);
 }
+export interface RemoteChangedErrorOptions extends DriveSyncErrorOptions {
+    fileId: string;
+    /** Version this client last restored, or null if it has never restored this file. */
+    baseVersion: string | null;
+    /** Version currently on Drive. */
+    remoteVersion: string;
+    reason: 'remote-changed' | 'never-restored';
+}
+/**
+ * Thrown when a write would clobber remote content this client has not seen.
+ *
+ * There is deliberately no `force` option: the only way past this error is to
+ * restore the remote file with `files.read()`, which records the remote
+ * version as the new baseline. From there the caller may either merge the
+ * remote content into their own and write the merged result, or discard the
+ * remote content and write their local version — but both paths require
+ * having pulled the changed file first.
+ */
+export declare class RemoteChangedError extends DriveSyncError {
+    fileId: string;
+    baseVersion: string | null;
+    remoteVersion: string;
+    constructor(opts: RemoteChangedErrorOptions);
+}
 /** Thrown when the Google Identity Services script never loaded within the timeout. */
 export declare class GisLoadError extends Error {
     constructor(message?: string);
 }
+/** Thrown when the user cancels the Google Picker dialog. */
+export declare class PickerCancelledError extends DriveSyncError {
+    constructor(message?: string, opts?: DriveSyncErrorOptions);
+}

package/dist/errors.js

@@ -75,6 +75,30 @@ export class TransientError extends DriveSyncError {
         this.name = 'TransientError';
     }
 }
+/**
+ * Thrown when a write would clobber remote content this client has not seen.
+ *
+ * There is deliberately no `force` option: the only way past this error is to
+ * restore the remote file with `files.read()`, which records the remote
+ * version as the new baseline. From there the caller may either merge the
+ * remote content into their own and write the merged result, or discard the
+ * remote content and write their local version — but both paths require
+ * having pulled the changed file first.
+ */
+export class RemoteChangedError extends DriveSyncError {
+    fileId;
+    baseVersion;
+    remoteVersion;
+    constructor(opts) {
+        super(opts.reason === 'never-restored'
+            ? `File ${opts.fileId} has never been restored by this client; read() it before writing`
+            : `File ${opts.fileId} changed on Drive since it was last restored`, { status: 409, ...opts });
+        this.name = 'RemoteChangedError';
+        this.fileId = opts.fileId;
+        this.baseVersion = opts.baseVersion;
+        this.remoteVersion = opts.remoteVersion;
+    }
+}
 /** Thrown when the Google Identity Services script never loaded within the timeout. */
 export class GisLoadError extends Error {
     constructor(message = 'Google Identity Services failed to load in time') {
@@ -82,3 +106,10 @@ export class GisLoadError extends Error {
         this.name = 'GisLoadError';
     }
 }
+/** Thrown when the user cancels the Google Picker dialog. */
+export class PickerCancelledError extends DriveSyncError {
+    constructor(message = 'User cancelled the picker', opts) {
+        super(message, opts);
+        this.name = 'PickerCancelledError';
+    }
+}

package/dist/files.d.ts

@@ -1,5 +1,5 @@
 import type { Logger } from './logger.js';
-import type { FileRef } from './types.js';
+import type { FileRef, FileState } from './types.js';
 /** Scopes this library always requests/requires. */
 export declare const REQUIRED_SCOPES: string[];
 interface BaseCallOptions {
@@ -39,8 +39,31 @@ export interface WriteOptions extends BaseCallOptions {
  * so file content that happens to contain a literal boundary-looking string
  * can never corrupt the request (a known bug in a hand-rolled-boundary
  * implementation this replaces).
+ *
+ * When no fileId is given but a name is, an existing non-trashed file with
+ * that name (within `folderId`, when given) is looked up first and updated
+ * in place. Without this, a caller that syncs by name — having no id to
+ * hand back, e.g. on a fresh page load — would mint a brand-new Drive file
+ * on every single sync instead of updating the file already in use.
+ *
+ * Every update path is guarded: if the file changed on Drive since this
+ * client last restored it (or was never restored here at all), the write is
+ * refused with a RemoteChangedError instead of clobbering someone else's
+ * edit. See that error's docs for the two ways forward.
  */
 export declare function write(opts: WriteOptions): Promise<FileRef>;
+export interface StatusOptions extends BaseCallOptions {
+    fileId: string;
+}
+/**
+ * Cheap metadata-only drift probe — the primitive an app polls to notify the
+ * user that the file in use has moved on. Downloads no content, so it is safe
+ * to call on a timer or on window focus.
+ *
+ * `exists: false` means the file is gone (or invisible to this account).
+ * `changedSinceRestore: true` means a write would currently be refused.
+ */
+export declare function status(opts: StatusOptions): Promise<FileState>;
 export interface ListOptions extends BaseCallOptions {
     folderId?: string;
     mimeType?: string;

package/dist/files.js

@@ -1,6 +1,7 @@
 import { driveFetch } from './http.js';
 import { escapeQ } from './query.js';
-import { NotFoundError } from './errors.js';
+import { NotFoundError, RemoteChangedError } from './errors.js';
+import { getFileState, setFileState, clearFileState } from './storage.js';
 const DRIVE_BASE = 'https://www.googleapis.com/drive/v3';
 const UPLOAD_BASE = 'https://www.googleapis.com/upload/drive/v3';
 const FOLDER_MIME_TYPE = 'application/vnd.google-apps.folder';
@@ -9,6 +10,44 @@ export const REQUIRED_SCOPES = [
     'https://www.googleapis.com/auth/drive.file',
     'https://www.googleapis.com/auth/userinfo.email',
 ];
+/**
+ * Fetches just the fields needed for conflict detection. Returns null on a
+ * 404, matching read()'s treatment of a missing/invisible file.
+ */
+async function fetchRemoteVersion(opts) {
+    try {
+        const res = await driveFetch({
+            appId: opts.appId,
+            projectId: opts.projectId,
+            clientId: opts.clientId,
+            url: `${DRIVE_BASE}/files/${encodeURIComponent(opts.fileId)}?fields=${encodeURIComponent('id,name,version,modifiedTime')}`,
+            method: 'GET',
+            interactive: opts.interactive,
+            requiredScopes: REQUIRED_SCOPES,
+            logger: opts.logger,
+            fetchEmail: opts.fetchEmail,
+        });
+        const json = (await res.json());
+        if (json.version === undefined)
+            return null;
+        return { version: String(json.version), name: json.name, modifiedTime: json.modifiedTime };
+    }
+    catch (err) {
+        if (err instanceof NotFoundError)
+            return null;
+        throw err;
+    }
+}
+/** Records `version` as this client's baseline for `fileId`. */
+async function recordBaseline(opts, fileId, version) {
+    if (version === undefined)
+        return;
+    await setFileState(opts.appId, opts.projectId, {
+        fileId,
+        version: String(version),
+        syncedAt: Date.now(),
+    });
+}
 /**
  * Fetches a file's content. Returns `null` on a 404 rather than throwing,
  * since Drive 404s both for a genuinely wrong id and for a file the
@@ -18,6 +57,13 @@ export const REQUIRED_SCOPES = [
  */
 export async function read(opts) {
     try {
+        // Sampled BEFORE the content download, not after: if someone writes to
+        // the file mid-read, the baseline recorded below is then older than
+        // what is on Drive, so the next write is refused and the caller
+        // restores again. Sampling afterwards would instead mark an edit this
+        // caller never received as "seen", which is exactly the clobber this
+        // tracking exists to prevent.
+        const meta = await fetchRemoteVersion(opts);
         const res = await driveFetch({
             appId: opts.appId,
             projectId: opts.projectId,
@@ -33,7 +79,13 @@ export async function read(opts) {
         const isTextual = contentType === '' ||
             contentType.startsWith('text/') ||
             contentType.includes('application/json');
-        return isTextual ? await res.text() : await res.blob();
+        const content = isTextual ? await res.text() : await res.blob();
+        // Restoring the file makes the version just sampled this client's new
+        // baseline: the caller has now seen whatever anyone else wrote, so a
+        // subsequent write is no longer a blind clobber. This is the ONLY way a
+        // RemoteChangedError is cleared, which is why it runs on every read.
+        await recordBaseline(opts, opts.fileId, meta?.version);
+        return content;
     }
     catch (err) {
         if (err instanceof NotFoundError) {
@@ -54,10 +106,64 @@ export async function remove(opts) {
         logger: opts.logger,
         fetchEmail: opts.fetchEmail,
     });
+    // The baseline describes a file that no longer exists; leaving it behind
+    // would make a later file reusing this id look spuriously in sync.
+    await clearFileState(opts.appId, opts.projectId, opts.fileId);
 }
 function toBlob(content, mimeType) {
     return content instanceof Blob ? content : new Blob([content], { type: mimeType });
 }
+/**
+ * Refuses the write unless this client's baseline matches what is on Drive
+ * right now. `knownRemoteVersion` lets the name-resolution path reuse the
+ * version it already got from list() instead of paying a second round trip.
+ */
+async function assertNotStale(opts, fileId, knownRemoteVersion) {
+    const remoteVersion = knownRemoteVersion ?? (await fetchRemoteVersion({ ...opts, fileId }))?.version;
+    // No version reported (a fake/older backend that does not expose `version`,
+    // or a file that has just vanished) — nothing to compare against, so fall
+    // through rather than blocking the caller on a check we cannot perform.
+    if (remoteVersion === undefined)
+        return;
+    const baseline = await getFileState(opts.appId, opts.projectId, fileId);
+    if (!baseline) {
+        throw new RemoteChangedError({
+            fileId,
+            baseVersion: null,
+            remoteVersion,
+            reason: 'never-restored',
+        });
+    }
+    if (baseline.version !== remoteVersion) {
+        throw new RemoteChangedError({
+            fileId,
+            baseVersion: baseline.version,
+            remoteVersion,
+            reason: 'remote-changed',
+        });
+    }
+}
+async function updateContent(opts, fileId, knownRemoteVersion) {
+    await assertNotStale(opts, fileId, knownRemoteVersion);
+    const res = await driveFetch({
+        appId: opts.appId,
+        projectId: opts.projectId,
+        clientId: opts.clientId,
+        url: `${UPLOAD_BASE}/files/${encodeURIComponent(fileId)}?uploadType=media&fields=${encodeURIComponent('id,name,version')}`,
+        method: 'PATCH',
+        headers: { 'Content-Type': opts.mimeType },
+        body: opts.content,
+        interactive: opts.interactive,
+        requiredScopes: REQUIRED_SCOPES,
+        logger: opts.logger,
+        fetchEmail: opts.fetchEmail,
+    });
+    const json = (await res.json());
+    // The version we just produced becomes the new baseline, so back-to-back
+    // writes from this client never trip the staleness guard on themselves.
+    await recordBaseline(opts, json.id, json.version);
+    return { id: json.id, name: json.name ?? opts.name };
+}
 /**
  * Creates or updates a file's content. Updates (fileId provided) use the
  * media-upload endpoint with the raw body. Creates use a `FormData`
@@ -65,24 +171,36 @@ function toBlob(content, mimeType) {
  * so file content that happens to contain a literal boundary-looking string
  * can never corrupt the request (a known bug in a hand-rolled-boundary
  * implementation this replaces).
+ *
+ * When no fileId is given but a name is, an existing non-trashed file with
+ * that name (within `folderId`, when given) is looked up first and updated
+ * in place. Without this, a caller that syncs by name — having no id to
+ * hand back, e.g. on a fresh page load — would mint a brand-new Drive file
+ * on every single sync instead of updating the file already in use.
+ *
+ * Every update path is guarded: if the file changed on Drive since this
+ * client last restored it (or was never restored here at all), the write is
+ * refused with a RemoteChangedError instead of clobbering someone else's
+ * edit. See that error's docs for the two ways forward.
  */
 export async function write(opts) {
     if (opts.fileId) {
-        const res = await driveFetch({
+        return updateContent(opts, opts.fileId);
+    }
+    if (opts.name) {
+        const existing = await list({
             appId: opts.appId,
             projectId: opts.projectId,
             clientId: opts.clientId,
-            url: `${UPLOAD_BASE}/files/${encodeURIComponent(opts.fileId)}?uploadType=media`,
-            method: 'PATCH',
-            headers: { 'Content-Type': opts.mimeType },
-            body: opts.content,
+            folderId: opts.folderId,
+            nameEquals: opts.name,
             interactive: opts.interactive,
-            requiredScopes: REQUIRED_SCOPES,
             logger: opts.logger,
             fetchEmail: opts.fetchEmail,
         });
-        const json = (await res.json());
-        return { id: json.id, name: json.name ?? opts.name };
+        if (existing.length > 0) {
+            return updateContent(opts, existing[0].id, existing[0].version);
+        }
     }
     const metadata = {
         name: opts.name,
@@ -107,7 +225,7 @@ export async function write(opts) {
         appId: opts.appId,
         projectId: opts.projectId,
         clientId: opts.clientId,
-        url: `${UPLOAD_BASE}/files?uploadType=multipart&fields=id`,
+        url: `${UPLOAD_BASE}/files?uploadType=multipart&fields=${encodeURIComponent('id,version')}`,
         method: 'POST',
         headers: multipartContentType ? { 'Content-Type': multipartContentType } : undefined,
         body: multipartBody,
@@ -117,8 +235,46 @@ export async function write(opts) {
         fetchEmail: opts.fetchEmail,
     });
     const json = (await res.json());
+    // This client authored the file, so it starts out fully in sync.
+    await recordBaseline(opts, json.id, json.version);
     return { id: json.id, name: opts.name };
 }
+/**
+ * Cheap metadata-only drift probe — the primitive an app polls to notify the
+ * user that the file in use has moved on. Downloads no content, so it is safe
+ * to call on a timer or on window focus.
+ *
+ * `exists: false` means the file is gone (or invisible to this account).
+ * `changedSinceRestore: true` means a write would currently be refused.
+ */
+export async function status(opts) {
+    const [meta, baseline] = await Promise.all([
+        fetchRemoteVersion(opts),
+        getFileState(opts.appId, opts.projectId, opts.fileId),
+    ]);
+    if (!meta) {
+        return {
+            fileId: opts.fileId,
+            exists: false,
+            baseVersion: baseline?.version ?? null,
+            remoteVersion: null,
+            changedSinceRestore: false,
+            lastRestoredAt: baseline?.syncedAt ?? null,
+        };
+    }
+    return {
+        fileId: opts.fileId,
+        exists: true,
+        baseVersion: baseline?.version ?? null,
+        remoteVersion: meta.version,
+        // Never having restored the file counts as drift: this client cannot show
+        // that what it holds descends from what is on Drive, which is exactly the
+        // condition a write is refused under.
+        changedSinceRestore: !baseline || baseline.version !== meta.version,
+        remoteModifiedTime: meta.modifiedTime,
+        lastRestoredAt: baseline?.syncedAt ?? null,
+    };
+}
 function buildQuery(opts) {
     const clauses = [];
     if (opts.folderId) {
@@ -135,7 +291,9 @@ function buildQuery(opts) {
 }
 export async function list(opts) {
     const q = buildQuery(opts);
-    const url = `${DRIVE_BASE}/files?q=${encodeURIComponent(q)}&fields=${encodeURIComponent('files(id,name,mimeType)')}`;
+    // `version` comes back so the name-resolution path in write() can run its
+    // staleness check without a follow-up metadata fetch.
+    const url = `${DRIVE_BASE}/files?q=${encodeURIComponent(q)}&fields=${encodeURIComponent('files(id,name,mimeType,version)')}`;
     const res = await driveFetch({
         appId: opts.appId,
         projectId: opts.projectId,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import type { CallOptions, Connection, DriveSyncOptions, DrivePermission, FileRef } from './types.js';
-export type { DriveSyncOptions, Connection, StoredToken, FileRef, DrivePermission, CallOptions } from './types.js';
+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 } from './types.js';
 export * from './errors.js';
 export interface FilesHandle {
     list(opts?: {
@@ -7,7 +7,16 @@ export interface FilesHandle {
         mimeType?: string;
         nameEquals?: string;
     }, callOpts?: CallOptions): Promise<FileRef[]>;
+    /**
+     * Fetches content AND records the file's current remote version as this
+     * client's baseline — the only way to clear a RemoteChangedError.
+     */
     read(fileId: string, callOpts?: CallOptions): Promise<string | Blob | null>;
+    /**
+     * Metadata-only check for whether the file changed since it was last
+     * restored here. Downloads no content; safe to poll.
+     */
+    status(fileId: string, callOpts?: CallOptions): Promise<FileState>;
     write(opts: {
         fileId?: string;
         folderId?: string;
@@ -48,6 +57,7 @@ export interface ProjectHandle {
      * drive a UI the user is actively interacting with.
      */
     getAccessToken(callOpts?: CallOptions): Promise<string>;
+    pickFile(options: PickFileOptions): Promise<PickedFile[]>;
     files: FilesHandle;
     permissions: PermissionsHandle;
 }

package/dist/index.js

@@ -3,6 +3,7 @@ import { connect as connectImpl, getConnection as getConnectionImpl, disconnect
 import { reconcile as reconcileImpl, dropProject as dropProjectImpl } from './reconcile.js';
 import * as filesImpl from './files.js';
 import * as permissionsImpl from './permissions.js';
+import * as pickerImpl from './picker.js';
 import { warmUpIfNeeded } from './refresh.js';
 import { REQUIRED_SCOPES } from './files.js';
 import { createBroadcast } from './broadcast.js';
@@ -138,6 +139,9 @@ export function createDriveSync(options) {
             read(fileId, callOpts) {
                 return filesImpl.read({ ...base, fileId, interactive: callOpts?.interactive });
             },
+            status(fileId, callOpts) {
+                return filesImpl.status({ ...base, fileId, interactive: callOpts?.interactive });
+            },
             write(opts, callOpts) {
                 return filesImpl.write({ ...base, ...opts, interactive: callOpts?.interactive });
             },
@@ -204,6 +208,30 @@ export function createDriveSync(options) {
                     logger,
                 });
             },
+            async pickFile(options) {
+                const token = await getAccessTokenImpl({
+                    appId,
+                    projectId,
+                    clientId,
+                    scopes: REQUIRED_SCOPES,
+                    interactive: true,
+                    logger,
+                });
+                const picked = await pickerImpl.openPicker({
+                    apiKey: options.apiKey,
+                    oauthToken: token,
+                    appId: options.appId,
+                    mimeTypes: options.mimeTypes,
+                    multiSelect: options.multiSelect,
+                    parentFolderId: options.parentFolderId,
+                });
+                const results = [];
+                for (const p of picked) {
+                    const content = await filesImpl.read({ ...base, fileId: p.fileId, interactive: true });
+                    results.push({ fileId: p.fileId, name: p.name, mimeType: p.mimeType, content });
+                }
+                return results;
+            },
             files,
             permissions,
         };

package/dist/picker.d.ts

@@ -0,0 +1,95 @@
+import type { WorkspaceMimeShorthand } from './types.js';
+/**
+ * Minimal ambient type declarations for Google Picker and GIS APIs.
+ * These allow TypeScript to recognize window.gapi and window.google.picker
+ * without importing the actual Google libraries.
+ */
+declare global {
+    interface Window {
+        gapi?: {
+            load(api: string, callback: () => void): void;
+        };
+        google?: {
+            picker?: {
+                PickerBuilder: new (...args: any[]) => PickerBuilder;
+                DocsView: new (...args: any[]) => DocsView;
+                Action: {
+                    PICKED: string;
+                    CANCEL: string;
+                };
+                ViewId: {
+                    DOCS: string;
+                };
+                Feature: {
+                    MULTISELECT_ENABLED: string;
+                };
+            };
+        };
+    }
+}
+interface PickerBuilder {
+    addView(view: DocsView): PickerBuilder;
+    setOAuthToken(token: string): PickerBuilder;
+    setDeveloperKey(key: string): PickerBuilder;
+    setAppId(appId: string): PickerBuilder;
+    enableFeature(feature: string): PickerBuilder;
+    setCallback(callback: (data: PickerResponse) => void): PickerBuilder;
+    build(): PickerInstance;
+}
+interface DocsView {
+    setMimeTypes(types: string): DocsView;
+    setParent(folderId: string): DocsView;
+}
+interface PickerInstance {
+    setVisible(visible: boolean): void;
+}
+interface PickerResponse {
+    action?: string;
+    docs?: PickerDocument[];
+}
+interface PickerDocument {
+    id: string;
+    name: string;
+    mimeType: string;
+}
+/**
+ * Test-only export: resets the script load cache, allowing tests to
+ * re-inject or mock the picker script. Exported normally (not conditionally gated)
+ * so tests can import and call it directly.
+ */
+export declare function __resetPickerScriptCacheForTests(): void;
+export interface OpenPickerOptions {
+    apiKey: string;
+    oauthToken: string;
+    /**
+     * The Cloud project *number* of the OAuth client that minted `oauthToken`.
+     * Required: this library requests only the `drive.file` scope, and Picker
+     * refuses to run a scoped session it cannot attribute to an app. Omit it and
+     * Picker discards the OAuth token, falls back to its own sign-in prompt, and
+     * then fails the unauthenticated developer-key check with "The API developer
+     * key is invalid" — even though the key and its referrer restrictions are fine.
+     */
+    appId: string;
+    mimeTypes?: (string | WorkspaceMimeShorthand)[];
+    multiSelect?: boolean;
+    parentFolderId?: string;
+}
+export interface PickedFile {
+    fileId: string;
+    name: string;
+    mimeType: string;
+}
+/**
+ * Opens the Google Picker dialog for file selection, returning a promise
+ * that resolves with the selected files or rejects if the user cancels.
+ *
+ * The picker is configured with optional MIME type filters, multi-select
+ * support, and a parent folder constraint.
+ *
+ * @param opts - Configuration including API key, OAuth token, and picker options
+ * @returns Promise resolving to an array of picked files
+ * @throws PickerCancelledError if the user cancels the dialog
+ * @throws Error if the Picker script fails to load or configuration fails
+ */
+export declare function openPicker(opts: OpenPickerOptions): Promise<PickedFile[]>;
+export {};

package/dist/picker.js

@@ -0,0 +1,140 @@
+import { PickerCancelledError } from './errors.js';
+/**
+ * Maps Google Workspace document type shorthands to their full MIME types.
+ */
+const WORKSPACE_MIME_SHORTHAND = {
+    docs: 'application/vnd.google-apps.document',
+    sheets: 'application/vnd.google-apps.spreadsheet',
+    slides: 'application/vnd.google-apps.presentation',
+    forms: 'application/vnd.google-apps.form',
+    drawings: 'application/vnd.google-apps.drawing',
+};
+/**
+ * Module-level cache for the Picker script loading promise.
+ * Reused across multiple openPicker() calls to avoid re-injecting the script.
+ */
+let scriptLoadPromise = null;
+/**
+ * Resolves an optional array of MIME types, expanding shorthand tokens
+ * (e.g., 'docs', 'sheets') to their full `application/vnd.google-apps.*` equivalents
+ * and passing literal MIME strings through unchanged.
+ *
+ * @param mimeTypes - Array containing strings and/or WorkspaceMimeShorthand tokens
+ * @returns Expanded array of MIME type strings, or undefined if input is undefined
+ */
+function resolveMimeTypes(mimeTypes) {
+    if (!mimeTypes) {
+        return undefined;
+    }
+    return mimeTypes.map((type) => {
+        if (type in WORKSPACE_MIME_SHORTHAND) {
+            return WORKSPACE_MIME_SHORTHAND[type];
+        }
+        return type;
+    });
+}
+/**
+ * Ensures the Google Picker API is loaded by:
+ * 1. Checking if window.google.picker already exists (e.g., from a test fake)
+ * 2. Reusing a pending script load if one is already in progress
+ * 3. Otherwise, injecting the picker script and waiting for gapi.load('picker')
+ *
+ * On script error, resets the cache so a retry will re-inject.
+ *
+ * @throws Error if script load fails
+ */
+async function ensurePickerLoaded() {
+    // Already loaded (e.g., by a test fake or prior successful load)
+    if (window.google?.picker) {
+        return;
+    }
+    // Script load already in progress; reuse the existing promise
+    if (scriptLoadPromise) {
+        return scriptLoadPromise;
+    }
+    // Inject the Picker script and set up the load promise
+    scriptLoadPromise = new Promise((resolve, reject) => {
+        const script = document.createElement('script');
+        script.src = 'https://apis.google.com/js/api.js';
+        script.onload = () => {
+            // Script loaded; now request the Picker API
+            window.gapi.load('picker', () => {
+                resolve();
+            });
+        };
+        script.onerror = () => {
+            // Script failed to load; reset cache so retry can re-inject
+            scriptLoadPromise = null;
+            reject(new Error('Failed to load Google Picker script'));
+        };
+        document.head.appendChild(script);
+    });
+    return scriptLoadPromise;
+}
+/**
+ * Test-only export: resets the script load cache, allowing tests to
+ * re-inject or mock the picker script. Exported normally (not conditionally gated)
+ * so tests can import and call it directly.
+ */
+export function __resetPickerScriptCacheForTests() {
+    scriptLoadPromise = null;
+}
+/**
+ * Opens the Google Picker dialog for file selection, returning a promise
+ * that resolves with the selected files or rejects if the user cancels.
+ *
+ * The picker is configured with optional MIME type filters, multi-select
+ * support, and a parent folder constraint.
+ *
+ * @param opts - Configuration including API key, OAuth token, and picker options
+ * @returns Promise resolving to an array of picked files
+ * @throws PickerCancelledError if the user cancels the dialog
+ * @throws Error if the Picker script fails to load or configuration fails
+ */
+export async function openPicker(opts) {
+    // Ensure the Picker API is available
+    await ensurePickerLoaded();
+    // Create and configure a DocsView for file browsing
+    const docsView = new window.google.picker.DocsView();
+    // Apply MIME type filters if provided
+    const resolvedMimes = resolveMimeTypes(opts.mimeTypes);
+    if (resolvedMimes) {
+        docsView.setMimeTypes(resolvedMimes.join(','));
+    }
+    // Constrain to a specific parent folder if provided
+    if (opts.parentFolderId) {
+        docsView.setParent(opts.parentFolderId);
+    }
+    // Create and configure the PickerBuilder
+    const pickerBuilder = new window.google.picker.PickerBuilder();
+    pickerBuilder
+        .addView(docsView)
+        .setOAuthToken(opts.oauthToken)
+        .setDeveloperKey(opts.apiKey)
+        .setAppId(opts.appId);
+    // Enable multi-select if requested
+    if (opts.multiSelect) {
+        pickerBuilder.enableFeature(window.google.picker.Feature.MULTISELECT_ENABLED);
+    }
+    // Set up the response handler and build the picker
+    return new Promise((resolve, reject) => {
+        pickerBuilder.setCallback((data) => {
+            // User picked files
+            if (data.action === window.google.picker.Action.PICKED && data.docs) {
+                const picked = data.docs.map((doc) => ({
+                    fileId: doc.id,
+                    name: doc.name,
+                    mimeType: doc.mimeType,
+                }));
+                resolve(picked);
+                return;
+            }
+            // User cancelled
+            if (data.action === window.google.picker.Action.CANCEL) {
+                reject(new PickerCancelledError());
+                return;
+            }
+        });
+        pickerBuilder.build().setVisible(true);
+    });
+}

package/dist/storage.d.ts

@@ -6,10 +6,21 @@ export interface ConnRecord {
     grantedScopes: string[];
     connectedAt: number;
 }
+/**
+ * Per-file sync baseline: the Drive `version` this client last restored (via
+ * files.read()) or last successfully wrote. A write is only allowed when the
+ * file's current remote version still matches this — see files.ts.
+ */
+export interface FileStateRecord {
+    fileId: string;
+    version: string;
+    /** Epoch ms at which this baseline was recorded. */
+    syncedAt: number;
+}
 interface AuthDbSchema extends DBSchema {
     auth: {
         key: string;
-        value: ConnRecord | StoredToken;
+        value: ConnRecord | StoredToken | FileStateRecord;
     };
 }
 export declare function openAuthDb(appId: string, projectId: string): Promise<IDBPDatabase<AuthDbSchema>>;
@@ -24,4 +35,7 @@ export declare function clearConn(appId: string, projectId: string): Promise<voi
 export declare function getToken(appId: string, projectId: string): Promise<StoredToken | undefined>;
 export declare function setToken(appId: string, projectId: string, token: StoredToken): Promise<void>;
 export declare function clearToken(appId: string, projectId: string): Promise<void>;
+export declare function getFileState(appId: string, projectId: string, fileId: string): Promise<FileStateRecord | undefined>;
+export declare function setFileState(appId: string, projectId: string, state: FileStateRecord): Promise<void>;
+export declare function clearFileState(appId: string, projectId: string, fileId: string): Promise<void>;
 export {};

package/dist/storage.js

@@ -2,6 +2,18 @@ import { openDB } from 'idb';
 const AUTH_STORE = 'auth';
 const CONN_KEY = 'conn';
 const TOKEN_KEY = 'token';
+/**
+ * File baselines live in the existing 'auth' store under a namespaced key
+ * rather than in a store of their own, deliberately: adding a store means
+ * bumping the DB version, and an upgrade cannot run while ANY other
+ * connection still holds the old version open. Older tabs run older code
+ * that has no way to know it should close, so the upgrade would block
+ * indefinitely and every Drive call — which needs this DB for its token —
+ * would hang rather than fail. Keeping the schema at v1 avoids that entirely.
+ */
+function fileKey(fileId) {
+    return `file:${fileId}`;
+}
 function dbName(appId, projectId) {
     return `owa-drive-${appId}-${projectId}`;
 }
@@ -19,6 +31,11 @@ export function openAuthDb(appId, projectId) {
                     db.createObjectStore(AUTH_STORE);
                 }
             },
+            // Defence for any FUTURE version bump: close this connection as soon as
+            // another tab needs to upgrade, so it is never the thing blocking.
+            blocking() {
+                void evictDbHandle(appId, projectId);
+            },
         });
         dbCache.set(key, handle);
     }
@@ -68,3 +85,16 @@ export async function clearToken(appId, projectId) {
     const db = await openAuthDb(appId, projectId);
     await db.delete(AUTH_STORE, TOKEN_KEY);
 }
+export async function getFileState(appId, projectId, fileId) {
+    const db = await openAuthDb(appId, projectId);
+    const value = await db.get(AUTH_STORE, fileKey(fileId));
+    return value;
+}
+export async function setFileState(appId, projectId, state) {
+    const db = await openAuthDb(appId, projectId);
+    await db.put(AUTH_STORE, state, fileKey(state.fileId));
+}
+export async function clearFileState(appId, projectId, fileId) {
+    const db = await openAuthDb(appId, projectId);
+    await db.delete(AUTH_STORE, fileKey(fileId));
+}

package/dist/testing/driveFake.d.ts

@@ -20,6 +20,11 @@ export interface DriveFakeFile {
     content: string;
     contentType?: string;
     trashed?: boolean;
+    /**
+     * Drive's monotonic per-file change counter, bumped on every mutation.
+     * Optional so tests may seed files without it; treated as 1 when absent.
+     */
+    version?: number;
 }
 export interface DriveFakePermission {
     id: string;
@@ -44,6 +49,11 @@ export interface DriveFake {
     reset(): void;
     /** Inspect current in-memory files, keyed by id. */
     readonly files: Map<string, DriveFakeFile>;
+    /**
+     * Simulate another client editing the file: replaces content and bumps
+     * `version`, exactly as a real out-of-band Drive write would.
+     */
+    externalEdit(fileId: string, content: string): void;
     /** Inspect current in-memory permissions, keyed by fileId then permission id. */
     readonly permissions: Map<string, Map<string, DriveFakePermission>>;
 }

package/dist/testing/driveFake.js

@@ -142,7 +142,7 @@ export function createDriveFake() {
         return override;
     }
     function fileToMetadata(f) {
-        return { id: f.id, name: f.name, mimeType: f.mimeType, parents: f.parents };
+        return { id: f.id, name: f.name, mimeType: f.mimeType, parents: f.parents, version: String(f.version ?? 1) };
     }
     async function handleFilesList(url) {
         const q = url.searchParams.get('q') ?? '';
@@ -218,6 +218,7 @@ export function createDriveFake() {
             parents: Array.isArray(metadata.parents) ? metadata.parents : [],
             content,
             contentType: mediaType,
+            version: 1,
         };
         files.set(id, file);
         if (mimeType === FOLDER_MIME_TYPE) {
@@ -237,6 +238,7 @@ export function createDriveFake() {
             const contentType = getHeader(init, 'Content-Type');
             if (contentType)
                 file.contentType = contentType;
+            file.version = (file.version ?? 1) + 1;
             return jsonResponse(fileToMetadata(file));
         }
         if (uploadType === 'multipart') {
@@ -254,6 +256,7 @@ export function createDriveFake() {
                 file.content = parsed.mediaContent;
                 if (parsed.mediaType)
                     file.contentType = parsed.mediaType;
+                file.version = (file.version ?? 1) + 1;
             }
             return jsonResponse(fileToMetadata(file));
         }
@@ -285,6 +288,7 @@ export function createDriveFake() {
             const removeSet = new Set(removeParents.split(','));
             file.parents = file.parents.filter((p) => !removeSet.has(p));
         }
+        file.version = (file.version ?? 1) + 1;
         return jsonResponse(fileToMetadata(file));
     }
     async function handleFileDelete(id) {
@@ -411,6 +415,13 @@ export function createDriveFake() {
                 remaining: opts?.times ?? 1,
             });
         },
+        externalEdit(fileId, content) {
+            const file = files.get(fileId);
+            if (!file)
+                throw new Error(`driveFake.externalEdit: unknown file ${fileId}`);
+            file.content = content;
+            file.version = (file.version ?? 1) + 1;
+        },
         reset() {
             files.clear();
             permissions.clear();

package/dist/testing/gisFake.d.ts

@@ -50,6 +50,12 @@ export interface GisFake {
     calls: GisRecordedCall[];
     /** Queue a response to be delivered to the next `requestAccessToken` call. */
     queueResponse(response: GisTokenResponse): void;
+    /**
+     * Queue a popup-level failure for the next `requestAccessToken` call,
+     * delivered via `error_callback` — the channel the real GIS client uses
+     * for a blocked or dismissed popup, which never reaches `callback`.
+     */
+    queuePopupError(type: string): void;
     /** Stub `window.google.accounts.oauth2.initTokenClient` with this fake. */
     install(): void;
     /** Remove the stub installed by `install()`, restoring prior state. */

package/dist/testing/gisFake.js

@@ -15,6 +15,7 @@
  */
 export function createGisFake() {
     const responseQueue = [];
+    const popupErrorQueue = [];
     const calls = [];
     let previousGoogle;
     let hadGoogle = false;
@@ -32,6 +33,14 @@ export function createGisFake() {
                 const hint = overrideConfig?.hint ?? config.hint;
                 const scope = overrideConfig?.scope ?? config.scope ?? '';
                 calls.push({ prompt, hint, scope });
+                const popupError = popupErrorQueue.shift();
+                if (popupError) {
+                    const errorCallback = config.error_callback;
+                    queueMicrotask(() => {
+                        errorCallback?.({ type: popupError });
+                    });
+                    return;
+                }
                 const response = nextResponse();
                 const callback = config.callback;
                 // Deliver asynchronously (microtask), matching the real GIS client's
@@ -54,6 +63,9 @@ export function createGisFake() {
         queueResponse(response) {
             responseQueue.push(response);
         },
+        queuePopupError(type) {
+            popupErrorQueue.push(type);
+        },
         install() {
             const w = globalThis;
             hadGoogle = Object.prototype.hasOwnProperty.call(w, 'google');
@@ -80,6 +92,7 @@ export function createGisFake() {
         },
         reset() {
             responseQueue.length = 0;
+            popupErrorQueue.length = 0;
             calls.length = 0;
         },
     };

package/dist/testing/index.d.ts

@@ -2,3 +2,5 @@ export { createGisFake } from './gisFake.js';
 export type { GisFake, GisTokenResponse, GisRecordedCall } from './gisFake.js';
 export { createDriveFake } from './driveFake.js';
 export type { DriveFake, DriveFakeFile, DriveFakePermission, StatusOverrideOptions } from './driveFake.js';
+export { createPickerFake } from './pickerFake.js';
+export type { PickerFake, PickerFakeFile, PickerRecordedCall } from './pickerFake.js';

package/dist/testing/index.js

@@ -1,2 +1,3 @@
 export { createGisFake } from './gisFake.js';
 export { createDriveFake } from './driveFake.js';
+export { createPickerFake } from './pickerFake.js';

package/dist/testing/pickerFake.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A scriptable double for Google Picker (google.picker),
+ * for use in tests of code that calls `window.google.picker.PickerBuilder`
+ * and related APIs.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const pickerFake = createPickerFake()
+ * pickerFake.install()
+ * // ... exercise code under test that calls openPicker() ...
+ * pickerFake.simulatePick([{ fileId: '123', name: 'doc.txt', mimeType: 'text/plain' }])
+ * await expect(openPickerPromise).resolves.toEqual([...])
+ * expect(pickerFake.calls).toHaveLength(1)
+ * ```
+ */
+export interface PickerFakeFile {
+    fileId: string;
+    name: string;
+    mimeType: string;
+}
+export interface PickerRecordedCall {
+    oauthToken?: string;
+    developerKey?: string;
+    appId?: string;
+    views: Array<{
+        mimeTypes?: string;
+        parentId?: string;
+    }>;
+    features: string[];
+}
+export interface PickerFake {
+    /** All PickerBuilder constructions and their configurations, in order. */
+    calls: PickerRecordedCall[];
+    /** Simulate user picking files; invokes the picker's callback asynchronously. */
+    simulatePick(files: PickerFakeFile[]): void;
+    /** Simulate user cancelling; invokes the picker's callback asynchronously. */
+    simulateCancel(): void;
+    /** Stub window.gapi and window.google.picker with this fake. */
+    install(): void;
+    /** Remove the stub installed by `install()`, restoring prior state. */
+    uninstall(): void;
+    /** Clear call history and stored callback state. */
+    reset(): void;
+}
+export declare function createPickerFake(): PickerFake;

package/dist/testing/pickerFake.js

@@ -0,0 +1,189 @@
+/**
+ * A scriptable double for Google Picker (google.picker),
+ * for use in tests of code that calls `window.google.picker.PickerBuilder`
+ * and related APIs.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const pickerFake = createPickerFake()
+ * pickerFake.install()
+ * // ... exercise code under test that calls openPicker() ...
+ * pickerFake.simulatePick([{ fileId: '123', name: 'doc.txt', mimeType: 'text/plain' }])
+ * await expect(openPickerPromise).resolves.toEqual([...])
+ * expect(pickerFake.calls).toHaveLength(1)
+ * ```
+ */
+export function createPickerFake() {
+    const calls = [];
+    let storedCallback = null;
+    let previousGapi;
+    let hadGapi = false;
+    let previousGoogle;
+    let hadGoogle = false;
+    let previousGooglePicker;
+    let hadGooglePicker = false;
+    /**
+     * Fake DocsView class for stubbing window.google.picker.DocsView.
+     * Stores MIME types and parent folder ID, and is chainable.
+     */
+    class FakeDocsView {
+        mimeTypes;
+        parentId;
+        setMimeTypes(types) {
+            this.mimeTypes = types;
+            return this;
+        }
+        setParent(folderId) {
+            this.parentId = folderId;
+            return this;
+        }
+    }
+    /**
+     * Fake PickerInstance (returned by PickerBuilder.build()).
+     * When setVisible(true) is called, it's recorded but callback is not fired
+     * until simulatePick or simulateCancel is called.
+     */
+    class FakePickerInstance {
+        setVisible(visible) {
+            // Visibility change is recorded implicitly by the builder construction.
+            // The callback will be triggered by simulatePick/simulateCancel.
+        }
+    }
+    /**
+     * Fake PickerBuilder class for stubbing window.google.picker.PickerBuilder.
+     * Chainable methods all return `this`, and build() returns a FakePickerInstance.
+     */
+    class FakePickerBuilder {
+        currentCall = {
+            views: [],
+            features: [],
+        };
+        addView(view) {
+            this.currentCall.views.push({
+                mimeTypes: view.mimeTypes,
+                parentId: view.parentId,
+            });
+            return this;
+        }
+        setOAuthToken(token) {
+            this.currentCall.oauthToken = token;
+            return this;
+        }
+        setDeveloperKey(key) {
+            this.currentCall.developerKey = key;
+            return this;
+        }
+        setAppId(appId) {
+            this.currentCall.appId = appId;
+            return this;
+        }
+        enableFeature(feature) {
+            this.currentCall.features.push(feature);
+            return this;
+        }
+        setCallback(callback) {
+            storedCallback = callback;
+            return this;
+        }
+        build() {
+            // Record the call once build() is invoked (not before, so all config is captured)
+            calls.push(this.currentCall);
+            return new FakePickerInstance();
+        }
+    }
+    return {
+        calls,
+        simulatePick(files) {
+            if (!storedCallback) {
+                return;
+            }
+            const callback = storedCallback;
+            queueMicrotask(() => {
+                callback({
+                    action: 'picked',
+                    docs: files.map((file) => ({
+                        id: file.fileId,
+                        name: file.name,
+                        mimeType: file.mimeType,
+                    })),
+                });
+            });
+        },
+        simulateCancel() {
+            if (!storedCallback) {
+                return;
+            }
+            const callback = storedCallback;
+            queueMicrotask(() => {
+                callback({
+                    action: 'cancel',
+                });
+            });
+        },
+        install() {
+            const w = globalThis;
+            // Save and replace window.gapi
+            hadGapi = Object.prototype.hasOwnProperty.call(w, 'gapi');
+            previousGapi = w.gapi;
+            w.gapi = {
+                load(api, callback) {
+                    if (api === 'picker') {
+                        queueMicrotask(callback);
+                    }
+                },
+            };
+            // Save and replace window.google
+            hadGoogle = Object.prototype.hasOwnProperty.call(w, 'google');
+            previousGoogle = w.google;
+            if (!w.google) {
+                w.google = {};
+            }
+            // Save and replace window.google.picker
+            hadGooglePicker = Object.prototype.hasOwnProperty.call(w.google, 'picker');
+            previousGooglePicker = w.google.picker;
+            w.google.picker = {
+                PickerBuilder: FakePickerBuilder,
+                DocsView: FakeDocsView,
+                Action: {
+                    PICKED: 'picked',
+                    CANCEL: 'cancel',
+                },
+                ViewId: {
+                    DOCS: 'docs',
+                },
+                Feature: {
+                    MULTISELECT_ENABLED: 'multiselect',
+                },
+            };
+        },
+        uninstall() {
+            const w = globalThis;
+            // Restore window.gapi
+            if (hadGapi) {
+                w.gapi = previousGapi;
+            }
+            else {
+                delete w.gapi;
+            }
+            // Restore window.google.picker
+            if (hadGooglePicker) {
+                w.google.picker = previousGooglePicker;
+            }
+            else if (w.google) {
+                delete w.google.picker;
+            }
+            // Restore window.google (if it was only created by install())
+            if (!hadGoogle) {
+                delete w.google;
+            }
+            else {
+                w.google = previousGoogle;
+            }
+        },
+        reset() {
+            calls.length = 0;
+            storedCallback = null;
+        },
+    };
+}

package/dist/token.js

@@ -114,6 +114,17 @@ async function acquireTokenUncoalesced(opts) {
                 }
                 resolve(res);
             },
+            // Without this, a popup that the browser blocks or the user closes
+            // settles NOTHING: GIS reports those through error_callback only, so
+            // the promise below would stay pending forever and every awaiting
+            // Drive call would hang until the caller's own timeout (if any).
+            error_callback: (err) => {
+                reject(new NeedsReauthError(err?.type === 'popup_failed_to_open'
+                    ? 'Google sign-in popup was blocked by the browser'
+                    : err?.type === 'popup_closed'
+                        ? 'Google sign-in popup was closed before completing'
+                        : `Google sign-in failed: ${err?.type ?? 'unknown error'}`, { reason: err?.type ?? 'gis_error' }));
+            },
         });
         opts.logger?.debug('drive-sync: requesting access token', {
             projectId: opts.projectId,

package/dist/types.d.ts

@@ -27,6 +27,26 @@ export interface StoredToken {
 export interface FileRef {
     id: string;
     name?: string;
+    /** Drive's monotonic change counter, when the call requested it. */
+    version?: string;
+}
+/**
+ * Sync state of one file relative to what this client last restored.
+ * Returned by `files.status()`.
+ */
+export interface FileState {
+    fileId: string;
+    /** False when the file is missing or not visible to the connected account. */
+    exists: boolean;
+    /** Version last restored/written by this client; null if never. */
+    baseVersion: string | null;
+    /** Version currently on Drive; null when the file does not exist. */
+    remoteVersion: string | null;
+    /** True when a write would be refused with a RemoteChangedError. */
+    changedSinceRestore: boolean;
+    remoteModifiedTime?: string;
+    /** Epoch ms of the last restore/write by this client; null if never. */
+    lastRestoredAt: number | null;
 }
 /** Drive permission shape as returned/accepted by the Drive Permissions API. */
 export interface DrivePermission {
@@ -35,6 +55,28 @@ export interface DrivePermission {
     role: string;
     emailAddress?: string;
 }
+/** Google Workspace MIME type shorthands for common document types. */
+export type WorkspaceMimeShorthand = 'docs' | 'sheets' | 'slides' | 'forms' | 'drawings';
+/** Options for opening the Google Picker to select files. */
+export interface PickFileOptions {
+    apiKey: string;
+    /**
+     * Cloud project *number* of the OAuth client configured on
+     * `DriveSyncOptions.clientId`. Passed to Picker's `setAppId()`; required
+     * because drive-sync only ever holds a `drive.file`-scoped token.
+     */
+    appId: string;
+    mimeTypes?: (string | WorkspaceMimeShorthand)[];
+    multiSelect?: boolean;
+    parentFolderId?: string;
+}
+/** File information returned after selection from Google Picker. */
+export interface PickedFile {
+    fileId: string;
+    name: string;
+    mimeType: string;
+    content: string | Blob | null;
+}
 /** Options accepted on every Drive-op call site. */
 export interface CallOptions {
     /** Whether an interactive (popup/redirect) auth flow may be triggered. Defaults to false. */

package/package.json

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