@open-webapp/drive-sync 0.1.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,7 +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 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' });
@@ -44,9 +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`), `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`).
 
-## 2. The 34 resolved design decisions
+`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 35 resolved design decisions
 
 **Bugs fixed (both source apps carried these):**
 
@@ -84,10 +88,11 @@ Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHand
 28. **No `folderId`/`fileId` persistence** — `ensureFolderPath()` and `write()` both return ids to the caller; nothing in `storage.ts`'s schema has a field for either.
 29. **One IndexedDB DB per project** — `storage.ts`'s `dbName(appId, projectId)` → `owa-drive-{appId}-{projectId}`, opened at version `1` with a single object store named `auth`.
 30. **`conn`/`token` split** — `storage.ts` stores a durable `ConnRecord` under key `'conn'` and an ephemeral `StoredToken` under key `'token'` in the same `auth` store; `clearToken` deletes only the `'token'` key.
-31. **Cross-tab BroadcastChannel — partially wired.** `broadcast.ts` implements `createBroadcast(appId)` with `postLogout`, `postToken`, and `onMessage`, channel-named `owa-drive-{appId}`, feature-detected to a no-op where `BroadcastChannel` is absent. In the shipped code, only `postLogout` is actually called (from `connection.ts`'s `disconnect()`). **Deviation from the plan:** nothing in `src/` calls `onMessage` or `postToken` — there is no listener that reacts to a `logout` broadcast in another tab, and no token-sharing path exists. The plumbing for both exists and is exported/testable, but "logout propagation" and "token sharing" as end-to-end behaviors are not wired up by this package itself; a consuming app would need to call `createBroadcast`/`onMessage` itself if it wants that (and `createBroadcast` is not currently exported from `index.ts`).
+31. **Cross-tab BroadcastChannel — fully wired.** `broadcast.ts` implements `createBroadcast(appId)` with `postLogout`, `postToken`, and `onMessage`, channel-named `owa-drive-{appId}`, feature-detected to a no-op where `BroadcastChannel` is absent. `connection.ts`'s `disconnect()` calls `postLogout`; `token.ts`'s `acquireToken` calls `postToken` after every successful acquisition (interactive `connect()`, silent `refreshSilently()`, and the plain warm-up fallback alike — one choke point right after the token lands in IndexedDB). `index.ts`'s `activate()` subscribes via `onMessage`: a `logout` message evicts this tab's cached IDB handle for that project (`evictDbHandle`) so a subsequent read sees the other tab's cleared storage; a `token` message calls `token.ts`'s `notifyExternalTokenRefresh(projectId)`, which lets this tab's next non-interactive `acquireToken` for that project skip its own GIS round-trip and re-read the fresh token from shared storage instead. Both directions are only live between `activate()` and its disposer — a project handle used without ever calling `.activate()` still reads/writes the same IndexedDB, just without the cross-tab shortcut.
 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
 
@@ -146,5 +151,5 @@ Wrong-account detection therefore covers exactly two silent paths — the 401-re
 - **`reconcile()` degrades to a no-op** where `indexedDB.databases()` is unsupported (Firefox, older Safari at time of writing). On those browsers, orphaned per-project auth databases from deleted projects are never automatically reclaimed unless the app calls `dropProject(id)` eagerly when it deletes the project — `reconcile()` is a safety net, not the primary cleanup mechanism.
 - **`files.ts`'s `read()` returns `null` on 404**, and that single value conflates two different situations: a genuinely wrong/nonexistent `fileId`, and a file that exists but that the currently-authenticated account cannot see (e.g. connected as the wrong Google account). The library cannot distinguish these — Drive itself returns an identical 404 for both — so callers that want to give an honest error message need to account for both cases themselves.
 - **Wrong-account detection is not universal.** As detailed in §4, it is implemented once, inside `connection.ts`'s `refreshSilently`, and is only reached via two call sites: the 401-triggered silent refresh in `http.ts`, and the proactive warm-up in `refresh.ts` (when a `fetchEmail` resolver is supplied — `index.ts` always supplies one). It is **not** checked on the interactive `connect()` path, and the `refresh.ts` fallback branch that calls `acquireToken` directly (used only when no `fetchEmail` is configured) bypasses it entirely. A non-401 Drive call that succeeds against a token silently swapped to the wrong account (rather than expiring first) would not be caught until some later 401 or explicit `getConnection()`/email check.
-- **Cross-tab `BroadcastChannel` support (`broadcast.ts`) is only half-used.** `postLogout` fires on `disconnect()`, but nothing in the package subscribes via `onMessage`, and `postToken` is never called — see decision #31 above. Multi-tab logout propagation and token sharing are not actual end-to-end behaviors of this package as shipped, only exposed building blocks.
+- **Cross-tab token sharing is best-effort, not a guarantee.** `notifyExternalTokenRefresh` (§4, decision #31) only ever skips ONE subsequent GIS round-trip per `token` broadcast received — a one-shot flag, not a durable "this project is externally fresh" cache. If two tabs both attempt a refresh in the same narrow window, both can still end up making their own GIS calls.
 - **`ensureFolderPath()`'s root-level lookup has no anchor.** Because the library only holds the `drive.file` scope, the first path segment is searched for by name/mimeType with no `in parents` constraint (every subsequent level is unambiguous, anchored to the previous level's id). Two folders with the same name at the top level anywhere the app can see are indistinguishable to this lookup; the first match wins.

package/dist/connection.d.ts

@@ -63,6 +63,30 @@ export interface GetConnectionOptions {
  * granted scopes on the stored connection are missing any required scope.
  */
 export declare function getConnection(opts: GetConnectionOptions): Promise<Connection | null>;
+export interface GetAccessTokenOptions {
+    appId: string;
+    projectId: string;
+    clientId: string;
+    scopes: string[];
+    /** Whether an interactive (popup) auth flow may be triggered if no usable cached token exists. */
+    interactive: boolean;
+    logger?: Logger;
+}
+/**
+ * Returns a raw OAuth access token for callers that must hand it directly to
+ * a Google-hosted widget this library does not control (namely Google
+ * Picker, which requires `setOAuthToken()`). This is a deliberate, narrow
+ * exception to Connection's "no secret material" contract documented in
+ * types.ts: Picker runs in Google's own popup/iframe and has no way to read
+ * a token this library keeps private, so the token must leave the library
+ * for that one integration to work at all. Callers should request this only
+ * to feed it straight to Picker, not to make their own Drive API calls
+ * (use `files`/`permissions` for that).
+ *
+ * Reuses a still-valid cached token as-is; otherwise acquires a fresh one
+ * via the normal token flow (interactive per `opts.interactive`).
+ */
+export declare function getAccessToken(opts: GetAccessTokenOptions): Promise<string>;
 export interface DisconnectOptions {
     appId: string;
     projectId: string;

package/dist/connection.js

@@ -2,6 +2,8 @@ import { getConn, setConn, clearConn, getToken, clearToken } from './storage.js'
 import { createBroadcast } from './broadcast.js';
 import { acquireToken } from './token.js';
 import { WrongAccountError } from './errors.js';
+/** Mirrors refresh.ts's own buffer: a cached token this close to expiry is treated as unusable. */
+const TOKEN_REUSE_BUFFER_MS = 5 * 60 * 1000;
 /**
  * Interactive connection flow: acquires a token with prompt: 'consent',
  * resolves the account email, and persists the durable Connection record.
@@ -74,6 +76,35 @@ export async function getConnection(opts) {
         expiresAt: token?.expiresAt ?? null,
     };
 }
+/**
+ * Returns a raw OAuth access token for callers that must hand it directly to
+ * a Google-hosted widget this library does not control (namely Google
+ * Picker, which requires `setOAuthToken()`). This is a deliberate, narrow
+ * exception to Connection's "no secret material" contract documented in
+ * types.ts: Picker runs in Google's own popup/iframe and has no way to read
+ * a token this library keeps private, so the token must leave the library
+ * for that one integration to work at all. Callers should request this only
+ * to feed it straight to Picker, not to make their own Drive API calls
+ * (use `files`/`permissions` for that).
+ *
+ * Reuses a still-valid cached token as-is; otherwise acquires a fresh one
+ * via the normal token flow (interactive per `opts.interactive`).
+ */
+export async function getAccessToken(opts) {
+    const cached = await getToken(opts.appId, opts.projectId);
+    if (cached && cached.expiresAt > Date.now() + TOKEN_REUSE_BUFFER_MS) {
+        return cached.accessToken;
+    }
+    const token = await acquireToken({
+        appId: opts.appId,
+        projectId: opts.projectId,
+        clientId: opts.clientId,
+        scopes: opts.scopes,
+        interactive: opts.interactive,
+        logger: opts.logger,
+    });
+    return token.accessToken;
+}
 /**
  * Disconnects a project: revokes the cached token (if any and if a
  * revokeFn was supplied), then unconditionally clears both the durable

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;
@@ -40,6 +49,15 @@ export interface ProjectHandle {
     getConnection(): Promise<Connection | null>;
     disconnect(): Promise<void>;
     ensureFolderPath(): Promise<string>;
+    /**
+     * Raw OAuth access token, for handing directly to Google Picker
+     * (`setOAuthToken()`) — see connection.ts's `getAccessToken` for why this
+     * is the one exception to this library otherwise never exposing token
+     * material. `interactive` defaults to true since callers use this to
+     * 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

@@ -1,8 +1,9 @@
 import { noOpLogger } from './logger.js';
-import { connect as connectImpl, getConnection as getConnectionImpl, disconnect as disconnectImpl } from './connection.js';
+import { connect as connectImpl, getConnection as getConnectionImpl, disconnect as disconnectImpl, getAccessToken as getAccessTokenImpl } from './connection.js';
 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 });
             },
@@ -194,6 +198,40 @@ export function createDriveSync(options) {
             ensureFolderPath() {
                 return filesImpl.ensureFolderPath({ ...base, folderPath });
             },
+            getAccessToken(callOpts) {
+                return getAccessTokenImpl({
+                    appId,
+                    projectId,
+                    clientId,
+                    scopes: REQUIRED_SCOPES,
+                    interactive: callOpts?.interactive ?? true,
+                    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,
         };