@open-webapp/drive-sync 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# @open-webapp/drive-sync
+
+Plain-TypeScript, React-free library for Google Drive OAuth token lifecycle,
+storage, and low-level Drive file/permission operations. Extracted from
+`open-webapp/planning` and `notesdiary/app`, which each had their own fork of
+this logic (and the same 11 bugs).
+
+The library owns auth + storage + Drive I/O. Merge logic, file naming, and
+content format stay app-side.
+
+## Usage
+
+```ts
+import { createDriveSync } from '@open-webapp/drive-sync'
+
+const drive = createDriveSync({
+  appId: 'my-app',
+  clientId: 'xxx.apps.googleusercontent.com',
+  folderPath: ['MyApp', 'Data'],
+})
+
+const dispose = drive.activate()
+await drive.reconcile(knownProjectIds)
+
+const p = drive.project(projectId)
+await p.connect()
+const folderId = await p.ensureFolderPath()
+await p.files.write({ folderId, name: 'data.json', content: '{}', mimeType: 'application/json' })
+```
+
+See `SPEC.md` for the full design: the 34 resolved decisions, storage layout,
+and refresh state machine. `SPEC.md` is descriptive, written from the shipped
+code — if it ever disagrees with the source, the source wins.
+
+## Testing
+
+Import fakes for GIS and Drive from the `./testing` subpath:
+
+```ts
+import { createGisFake, createDriveFake } from '@open-webapp/drive-sync/testing'
+```

package/SPEC.md

@@ -0,0 +1,150 @@
+# `@open-webapp/drive-sync` — Spec
+
+**Status: descriptive, not normative.** Written last, from the shipped code in `src/`. If anything here disagrees with the source, the source is right and this file should be corrected.
+
+## 1. Overview
+
+`drive-sync` is a plain-TypeScript (no React, one runtime dependency — `idb`), browser-only library that owns two things for an app that backs project data onto a user's Google Drive:
+
+- **OAuth token lifecycle**: acquiring, caching, silently refreshing, and revoking a Google Identity Services (GIS) access token, per project.
+- **Low-level Drive I/O**: file read/write/list/remove, folder-path resolution, and Drive permissions — all as thin, content-agnostic wrappers around the Drive v3 REST API.
+
+It deliberately does **not** implement any merge/diff logic, file-naming convention, or "sync" abstraction. There is no `sync()` call anywhere in the package. An app decides what a "project" contains, what its files are named, how conflicting versions get merged, and when to call `read`/`write` — the library only gets it there and back, authenticated, retried, and typed.
+
+### Public API
+
+`src/index.ts` exports one factory:
+
+```ts
+import { createDriveSync } from '@open-webapp/drive-sync';
+
+const drive = createDriveSync({
+  appId: 'planning',
+  clientId: GOOGLE_CLIENT_ID,
+  folderPath: ['OpenWebApp', 'Planning'],
+});
+
+const dispose = drive.activate();               // attach visibility/pageshow listeners
+await drive.reconcile(knownProjectIds);          // drop orphaned per-project auth DBs
+
+const p = drive.project(projectId);
+await p.connect();                               // interactive; prompt:'consent'
+const conn = await p.getConnection();            // { email, needsReauth, expiresAt } | null
+
+const folderId = await p.ensureFolderPath();
+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' });
+await p.permissions.grant({ fileId, type: 'user', role: 'writer', emailAddress: 'a@b.com' });
+
+await p.disconnect();
+await drive.dropProject(projectId);
+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`).
+
+## 2. The 34 resolved design decisions
+
+**Bugs fixed (both source apps carried these):**
+
+1. **Per-request token client, not a module singleton** — `token.ts`'s `acquireToken`/`acquireTokenUncoalesced` creates a fresh `initTokenClient` on every call; nothing closes over the first call's `projectId`.
+2. **Scope honored on every call** — the fresh client is configured with `opts.scopes.join(' ')` per call, not baked in once at init.
+3. **In-flight coalescing keyed by `(projectId, sorted scopes)`** — `token.ts`'s `coalesceKey` + `inFlight` map; concurrent calls for different projects/scopes never collide.
+4. **No clobbered resolvers** — `resolve`/`reject` are captured in each call's own `Promise` closure (`acquireTokenUncoalesced`), never stored on a module-level variable.
+5. **Real expiry** — `persistTokenResponse` reads `response.expires_in` and computes `Date.now() + expiresIn * 1000`; no hardcoded `3600`.
+6. **`grantedScopes` recorded** — `persistTokenResponse` splits `response.scope` and stores it on the token; `connection.ts`'s `connect()` also copies it onto the durable `ConnRecord`.
+7. **401 handled** — `http.ts`'s `performFetch` clears the token, retries once non-interactively, then throws `NeedsReauthError` (see §4).
+8. **`hint` on silent refresh** — every non-interactive `acquireToken` call is given `hint: <known email>`; wrong-account tokens are caught by `refreshSilently` (see below and §4).
+9. **`response.ok` checked before parsing** — `performFetch` never calls `.json()`/`.text()` on a response without checking `res.ok` first; every status branch is explicit.
+10. **429/5xx retry** — `performFetch`'s attempt loop, up to `MAX_ATTEMPTS = 3`, honoring `Retry-After`.
+11. **No hand-rolled multipart boundary** — `files.ts`'s `write()` (create path) builds a real `FormData`, serializes it via a throwaway `Request` to get fetch's own computed boundary/Content-Type, and forwards that verbatim.
+
+**Fixes adopted from whichever app had them right:**
+
+12. **GIS load guard** — `gis.ts`'s `waitForGoogleIdentityServices`: 100ms poll, 10s timeout, typed `GisLoadError`.
+13. **`ACCESS_TOKEN_SCOPE_INSUFFICIENT` handling** — `http.ts` checks the 403 body for that string and throws `ScopeInsufficientError`, clearing the token first.
+14. **`q=` escaping** — `query.ts`'s `escapeQ`: backslash escaped before quote (both apps had this wrong or partial; this is neither app's code, written fresh to the correct rule).
+15. **Structured errors, not string parsing** — `errors.ts`'s `DriveSyncError` subclasses carry `status`/`reason`/`retryAfter`/`fileId`/`expectedEmail`/`actualEmail` fields.
+16. **`disconnect()` early-returns the revoke POST** when no token is cached — `connection.ts`'s `disconnect()` checks `getToken()` before calling the injected `revokeFn`.
+
+**Other resolved decisions:**
+
+17. **`prompt` selection** — `token.ts`: `interactive ? 'consent' : 'none'`, with `hint` only ever attached on the non-interactive path.
+18. **Fully async surface** — no synchronous accessors anywhere in `index.ts`/`connection.ts`/`storage.ts`.
+19. **One connection object, not two** — `getConnection()` (`connection.ts`) returns `{ email, needsReauth, expiresAt } | null` rather than a separate `{authenticated, cachedToken}` shape.
+20. **Injectable no-op logger** — `logger.ts`'s `Logger` interface + `noOpLogger`, taken as `options.logger` in `createDriveSync`.
+21. **`FormData` multipart create** — see #11 above; implemented in `files.ts`.
+22. **Content-agnostic payload** — `WriteOptions.content: string | Blob` plus an explicit `mimeType` (`files.ts`).
+23. **`folderPath` supplied at factory time** — `DriveSyncOptions.folderPath: string[]`; `ensureFolderPath()` walks it (`files.ts`).
+24. **Retry policy** — bounded exponential backoff (`BASE_DELAY_MS * 2^(attempt-1)`), 3 attempts, `Retry-After` honored when present, and **no retry on any non-429 4xx** (`http.ts`).
+25–27. **App-side concerns kept out of the library** — `ensureJsonExtension`, CSV filename/content building, and any app-level `connectDriveSync`-style helper are not present anywhere in `src/`; the library only exposes `ensureFolderPath()` + `files.write()` for an app to build such helpers on top of.
+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`).
+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.
+
+## 3. Storage layout
+
+Each project gets its own IndexedDB database: **`owa-drive-{appId}-{projectId}`**, version 1, containing one object store, `auth` (`storage.ts`). The store holds exactly two keys:
+
+| Key | Shape | Lifetime |
+|---|---|---|
+| `conn` | `{ email, grantedScopes: string[], connectedAt: number }` | Durable — survives token expiry. Written by `connect()`. Cleared only by `disconnect()`. |
+| `token` | `{ accessToken, expiresAt, grantedScopes: string[] }` | Ephemeral. Written by `persistTokenResponse()` on every successful token acquisition. Cleared on 401 (`http.ts`), on `ScopeInsufficientError` (`http.ts`), on a detected wrong-account mismatch (`connection.ts`'s `refreshSilently`), and by `disconnect()`. |
+
+Open handles are cached in-process in a `Map<string, Promise<IDBPDatabase>>` keyed by `${appId}:${projectId}` (`storage.ts`'s `dbCache`), so repeated calls for the same project reuse one connection. `evictDbHandle` closes and drops that cache entry without deleting the underlying database — the deletion itself only happens in `reconcile.ts`.
+
+Two things trigger deleting the whole per-project database:
+
+- **`drive.dropProject(projectId)`** — the eager, app-driven path (e.g. called when a project is deleted in the host app).
+- **`drive.reconcile(knownProjectIds)`** — the safety net, run at boot: enumerates every `owa-drive-{appId}-*` database via `indexedDB.databases()` and deletes any whose trailing projectId is not in the supplied set. No-ops (does not throw) where `indexedDB.databases()` is unsupported.
+
+Nothing in this schema stores a Drive `folderId` or `fileId` — those stay app-side by design (#28 above).
+
+## 4. Refresh state machine
+
+Token acquisition always funnels through `token.ts`'s `acquireToken`, which is coalesced per `(projectId, sorted scopes)` and never keeps module-level mutable state across calls. Four distinct callers drive it, each representing a different "state":
+
+```
+[No connection]
+    |  connect() (connection.ts)
+    |  acquireToken({interactive:true})  -> prompt:'consent', no hint
+    v
+[Connected, token cached]  <---------------------------------------------+
+    |                                                                    |
+    | token missing/expired                                              | success
+    v                                                                    |
+[Silent refresh attempt] -- acquireToken({interactive:false, hint:email})+
+    |  triggered by 3 independent call sites:
+    |   (a) http.ts 401 handler        -> refreshSilently, retry original request ONCE
+    |   (b) refresh.ts warmUpIfNeeded  -> refreshSilently, proactive, background
+    |   (c) refresh.ts (no fetchEmail) -> plain acquireToken fallback, background only
+    |
+    +-- GIS error / no token -----------------> NeedsReauthError
+    +-- GIS returns token for the RIGHT email -> [Connected, token cached]
+    +-- GIS returns token for the WRONG email -> clearToken(); WrongAccountError
+```
+
+Concretely, by module:
+
+- **`token.ts`** is the only place that talks to GIS's `initTokenClient`. It does not know about "wrong account" — it just returns whatever token GIS hands back for the requested `(scopes, prompt, hint)`.
+- **`connection.ts`**'s `refreshSilently` is the *only* place that adds wrong-account verification: after `acquireToken({interactive:false, hint:expectedEmail})` resolves, it calls the injected `fetchEmail(token.accessToken)` and compares the result against `expectedEmail`. Mismatch → `clearToken()` then throw `WrongAccountError`; match → return the token.
+- **`http.ts`**'s `driveFetch`/`performFetch` is the 401 path: on a first 401 (not already a retry, not an interactive call), it clears the token and, if a `fetchEmail` was supplied and a connection's email is known, calls `refreshSilently`; otherwise falls back to a bare `acquireToken`. It retries the original request exactly once (`isRetryAfter401` flag) with whatever token comes back. A second 401, or any 401 on an interactive call, throws `NeedsReauthError` without retrying again. A `WrongAccountError` from `refreshSilently` is re-thrown as-is rather than being swallowed into `NeedsReauthError`.
+- **`refresh.ts`**'s `warmUpIfNeeded` is the proactive path: fired from `visibilitychange`→`visible` and `pageshow`(persisted, not hidden) listeners attached by `activate()`. It only acts if a `conn` record exists **and** the cached token is missing or within `REFRESH_BUFFER_MS` (5 minutes) of `expiresAt`. When a `fetchEmail` is configured it goes through `refreshSilently` (so wrong-account detection also covers this path); otherwise it falls back to a bare `acquireToken`. It never *starts* a new attempt while the document is hidden — visibility is checked before it is ever called, so an attempt already in flight from before the tab hid is left to finish on its own.
+- **`index.ts`**'s top-level `activate()` layers one global listener pair over `refresh.ts`'s per-call logic: it tracks every `projectId` ever passed to `.project(id)` in a `Set` and, on each visibility/pageshow event, calls `warmUpIfNeeded` for all of them (read live at fire time, so late-registered projects are still covered).
+
+Wrong-account detection therefore covers exactly two silent paths — the 401-retry-once in `http.ts` and the proactive warm-up in `refresh.ts`/`index.ts` — both of which are wired through `refreshSilently`. It does **not** cover the interactive `connect()` path (a user consenting is trusted at face value) nor any refresh path where the caller omitted `fetchEmail` (the `refresh.ts` fallback branch and any hand-rolled use of `acquireToken` directly).
+
+## 5. Known limitations / accepted tradeoffs
+
+- **`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.
+- **`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/broadcast.d.ts

@@ -0,0 +1,15 @@
+export interface BroadcastMessage {
+    type: 'logout' | 'token';
+    projectId: string;
+}
+export interface Broadcast {
+    postLogout(projectId: string): void;
+    postToken(projectId: string): void;
+    onMessage(handler: (msg: BroadcastMessage) => void): () => void;
+}
+/**
+ * Creates a cross-tab broadcast channel scoped to a single appId. Feature
+ * detects BroadcastChannel and no-ops gracefully in environments where it is
+ * unavailable (e.g. some server-side or older browser contexts).
+ */
+export declare function createBroadcast(appId: string): Broadcast;

package/dist/broadcast.js

@@ -0,0 +1,38 @@
+/**
+ * Creates a cross-tab broadcast channel scoped to a single appId. Feature
+ * detects BroadcastChannel and no-ops gracefully in environments where it is
+ * unavailable (e.g. some server-side or older browser contexts).
+ */
+export function createBroadcast(appId) {
+    if (typeof BroadcastChannel === 'undefined') {
+        return {
+            postLogout() { },
+            postToken() { },
+            onMessage() {
+                return () => { };
+            },
+        };
+    }
+    const channel = new BroadcastChannel(`owa-drive-${appId}`);
+    function post(type, projectId) {
+        const msg = { type, projectId };
+        channel.postMessage(msg);
+    }
+    return {
+        postLogout(projectId) {
+            post('logout', projectId);
+        },
+        postToken(projectId) {
+            post('token', projectId);
+        },
+        onMessage(handler) {
+            const listener = (event) => {
+                handler(event.data);
+            };
+            channel.addEventListener('message', listener);
+            return () => {
+                channel.removeEventListener('message', listener);
+            };
+        },
+    };
+}

package/dist/connection.d.ts

@@ -0,0 +1,84 @@
+import type { Logger } from './logger.js';
+import type { Connection, StoredToken } from './types.js';
+export interface ConnectOptions {
+    appId: string;
+    projectId: string;
+    clientId: string;
+    scopes: string[];
+    logger?: Logger;
+    /**
+     * Resolves the connected account's email from a fresh access token.
+     * Injected rather than implemented here because drive-sync does not yet
+     * have an http.ts (a later task); index.ts will wire this to a real fetch
+     * against the Google userinfo endpoint once http.ts exists.
+     */
+    fetchEmail: (accessToken: string) => Promise<string>;
+}
+/**
+ * Interactive connection flow: acquires a token with prompt: 'consent',
+ * resolves the account email, and persists the durable Connection record.
+ */
+export declare function connect(opts: ConnectOptions): Promise<Connection>;
+export interface RefreshSilentlyOptions {
+    appId: string;
+    projectId: string;
+    clientId: string;
+    scopes: string[];
+    /**
+     * The email the resulting token MUST belong to (i.e. the currently stored
+     * connection's email). GIS's `hint` is only ever a hint to Google — under
+     * some multi-login browser states it can silently hand back a valid token
+     * for a DIFFERENT account than the one hinted. This function is the single
+     * place that closes that gap for every non-interactive (silent) refresh of
+     * an EXISTING connection.
+     */
+    expectedEmail: string;
+    /** Resolves the account email from a fresh access token (same shape as
+     * ConnectOptions.fetchEmail — deliberately injected rather than
+     * implemented here, so this module still has no direct network
+     * dependency). */
+    fetchEmail: (accessToken: string) => Promise<string>;
+    logger?: Logger;
+}
+/**
+ * Wraps a non-interactive `acquireToken` call with account-identity
+ * verification: after GIS hands back a token, resolves the email it
+ * actually belongs to and compares it against `expectedEmail`. On mismatch,
+ * clears the now-suspect cached token (so a caller retrying does not reuse
+ * it) and throws `WrongAccountError` instead of returning the token.
+ *
+ * This is the ONLY place non-interactive refreshes for an existing
+ * connection should go through — http.ts's 401-retry path and refresh.ts's
+ * proactive warm-up both call this rather than `acquireToken` directly.
+ */
+export declare function refreshSilently(opts: RefreshSilentlyOptions): Promise<StoredToken>;
+export interface GetConnectionOptions {
+    appId: string;
+    projectId: string;
+    requiredScopes: string[];
+}
+/**
+ * Reads the durable connection + cached token from storage with NO network
+ * calls. needsReauth is computed purely from scope coverage: true if the
+ * granted scopes on the stored connection are missing any required scope.
+ */
+export declare function getConnection(opts: GetConnectionOptions): Promise<Connection | null>;
+export interface DisconnectOptions {
+    appId: string;
+    projectId: string;
+    /**
+     * Revokes the cached access token upstream. Injected because drive-sync
+     * does not yet have an http.ts; index.ts will wire this to a real fetch
+     * against the Google token revocation endpoint once http.ts exists. Only
+     * called when a token is actually cached — mirrors a fixed bug where the
+     * old code always POSTed a revoke request even when there was nothing to
+     * revoke.
+     */
+    revokeFn?: (accessToken: string) => Promise<void>;
+}
+/**
+ * Disconnects a project: revokes the cached token (if any and if a
+ * revokeFn was supplied), then unconditionally clears both the durable
+ * connection and the cached token, and broadcasts a logout to other tabs.
+ */
+export declare function disconnect(opts: DisconnectOptions): Promise<void>;

package/dist/connection.js

@@ -0,0 +1,90 @@
+import { getConn, setConn, clearConn, getToken, clearToken } from './storage.js';
+import { createBroadcast } from './broadcast.js';
+import { acquireToken } from './token.js';
+import { WrongAccountError } from './errors.js';
+/**
+ * Interactive connection flow: acquires a token with prompt: 'consent',
+ * resolves the account email, and persists the durable Connection record.
+ */
+export async function connect(opts) {
+    const token = await acquireToken({
+        appId: opts.appId,
+        projectId: opts.projectId,
+        clientId: opts.clientId,
+        scopes: opts.scopes,
+        interactive: true,
+        logger: opts.logger,
+    });
+    const email = await opts.fetchEmail(token.accessToken);
+    await setConn(opts.appId, opts.projectId, {
+        email,
+        grantedScopes: token.grantedScopes,
+        connectedAt: Date.now(),
+    });
+    return {
+        email,
+        needsReauth: false,
+        expiresAt: token.expiresAt,
+    };
+}
+/**
+ * Wraps a non-interactive `acquireToken` call with account-identity
+ * verification: after GIS hands back a token, resolves the email it
+ * actually belongs to and compares it against `expectedEmail`. On mismatch,
+ * clears the now-suspect cached token (so a caller retrying does not reuse
+ * it) and throws `WrongAccountError` instead of returning the token.
+ *
+ * This is the ONLY place non-interactive refreshes for an existing
+ * connection should go through — http.ts's 401-retry path and refresh.ts's
+ * proactive warm-up both call this rather than `acquireToken` directly.
+ */
+export async function refreshSilently(opts) {
+    const token = await acquireToken({
+        appId: opts.appId,
+        projectId: opts.projectId,
+        clientId: opts.clientId,
+        scopes: opts.scopes,
+        interactive: false,
+        hint: opts.expectedEmail,
+        logger: opts.logger,
+    });
+    const actualEmail = await opts.fetchEmail(token.accessToken);
+    if (actualEmail !== opts.expectedEmail) {
+        await clearToken(opts.appId, opts.projectId);
+        throw new WrongAccountError({ expectedEmail: opts.expectedEmail, actualEmail });
+    }
+    return token;
+}
+/**
+ * Reads the durable connection + cached token from storage with NO network
+ * calls. needsReauth is computed purely from scope coverage: true if the
+ * granted scopes on the stored connection are missing any required scope.
+ */
+export async function getConnection(opts) {
+    const conn = await getConn(opts.appId, opts.projectId);
+    if (!conn) {
+        return null;
+    }
+    const token = await getToken(opts.appId, opts.projectId);
+    const grantedScopes = new Set(conn.grantedScopes);
+    const needsReauth = opts.requiredScopes.some((scope) => !grantedScopes.has(scope));
+    return {
+        email: conn.email,
+        needsReauth,
+        expiresAt: token?.expiresAt ?? null,
+    };
+}
+/**
+ * Disconnects a project: revokes the cached token (if any and if a
+ * revokeFn was supplied), then unconditionally clears both the durable
+ * connection and the cached token, and broadcasts a logout to other tabs.
+ */
+export async function disconnect(opts) {
+    const token = await getToken(opts.appId, opts.projectId);
+    if (token && opts.revokeFn) {
+        await opts.revokeFn(token.accessToken);
+    }
+    await clearConn(opts.appId, opts.projectId);
+    await clearToken(opts.appId, opts.projectId);
+    createBroadcast(opts.appId).postLogout(opts.projectId);
+}

package/dist/errors.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Typed error classes for drive-sync. All carry structured fields (status,
+ * reason, email, fileId, retryAfter, etc.) rather than baking the only
+ * available information into a formatted message string, so callers can
+ * branch on error shape without string-parsing.
+ */
+export interface DriveSyncErrorOptions {
+    status?: number;
+    reason?: string;
+}
+export declare class DriveSyncError extends Error {
+    status?: number;
+    reason?: string;
+    constructor(message: string, opts?: DriveSyncErrorOptions);
+}
+/**
+ * Thrown when no usable token exists and the requested call is
+ * non-interactive (so no popup/redirect flow may be triggered to obtain one).
+ */
+export declare class NeedsReauthError extends DriveSyncError {
+    constructor(message?: string, opts?: DriveSyncErrorOptions);
+}
+/**
+ * Thrown on a 403 response with reason ACCESS_TOKEN_SCOPE_INSUFFICIENT.
+ */
+export declare class ScopeInsufficientError extends DriveSyncError {
+    constructor(message?: string, opts?: DriveSyncErrorOptions);
+}
+export interface WrongAccountErrorOptions extends DriveSyncErrorOptions {
+    expectedEmail: string;
+    actualEmail?: string;
+}
+/**
+ * Thrown when the authenticated account does not match the expected one
+ * (e.g. a silent refresh returned a token for a different Google account).
+ */
+export declare class WrongAccountError extends DriveSyncError {
+    expectedEmail: string;
+    actualEmail?: string;
+    /** Convenience alias mirroring the spec's `this.email` field (== actualEmail). */
+    email?: string;
+    constructor(opts: WrongAccountErrorOptions);
+}
+/** Thrown when a Drive file lookup returns 404. */
+export declare class NotFoundError extends DriveSyncError {
+    fileId: string;
+    constructor(fileId: string, opts?: DriveSyncErrorOptions);
+}
+export interface RateLimitedErrorOptions extends DriveSyncErrorOptions {
+    retryAfter?: number;
+}
+/** Thrown on a 429 response. */
+export declare class RateLimitedError extends DriveSyncError {
+    retryAfter?: number;
+    constructor(opts?: RateLimitedErrorOptions);
+}
+/** Generic 5xx-after-retries failure. */
+export declare class TransientError extends DriveSyncError {
+    constructor(message?: string, opts?: DriveSyncErrorOptions);
+}
+/** Thrown when the Google Identity Services script never loaded within the timeout. */
+export declare class GisLoadError extends Error {
+    constructor(message?: string);
+}

package/dist/errors.js

@@ -0,0 +1,84 @@
+/**
+ * Typed error classes for drive-sync. All carry structured fields (status,
+ * reason, email, fileId, retryAfter, etc.) rather than baking the only
+ * available information into a formatted message string, so callers can
+ * branch on error shape without string-parsing.
+ */
+export class DriveSyncError extends Error {
+    status;
+    reason;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'DriveSyncError';
+        this.status = opts?.status;
+        this.reason = opts?.reason;
+    }
+}
+/**
+ * Thrown when no usable token exists and the requested call is
+ * non-interactive (so no popup/redirect flow may be triggered to obtain one).
+ */
+export class NeedsReauthError extends DriveSyncError {
+    constructor(message = 'Reauthentication required', opts) {
+        super(message, opts);
+        this.name = 'NeedsReauthError';
+    }
+}
+/**
+ * Thrown on a 403 response with reason ACCESS_TOKEN_SCOPE_INSUFFICIENT.
+ */
+export class ScopeInsufficientError extends DriveSyncError {
+    constructor(message = 'Access token has insufficient scope', opts) {
+        super(message, { status: 403, reason: 'ACCESS_TOKEN_SCOPE_INSUFFICIENT', ...opts });
+        this.name = 'ScopeInsufficientError';
+    }
+}
+/**
+ * Thrown when the authenticated account does not match the expected one
+ * (e.g. a silent refresh returned a token for a different Google account).
+ */
+export class WrongAccountError extends DriveSyncError {
+    expectedEmail;
+    actualEmail;
+    /** Convenience alias mirroring the spec's `this.email` field (== actualEmail). */
+    email;
+    constructor(opts) {
+        super(`Wrong account: expected ${opts.expectedEmail}${opts.actualEmail ? `, got ${opts.actualEmail}` : ''}`, opts);
+        this.name = 'WrongAccountError';
+        this.expectedEmail = opts.expectedEmail;
+        this.actualEmail = opts.actualEmail;
+        this.email = opts.actualEmail;
+    }
+}
+/** Thrown when a Drive file lookup returns 404. */
+export class NotFoundError extends DriveSyncError {
+    fileId;
+    constructor(fileId, opts) {
+        super(`File not found: ${fileId}`, { status: 404, ...opts });
+        this.name = 'NotFoundError';
+        this.fileId = fileId;
+    }
+}
+/** Thrown on a 429 response. */
+export class RateLimitedError extends DriveSyncError {
+    retryAfter;
+    constructor(opts) {
+        super('Rate limited', { status: 429, ...opts });
+        this.name = 'RateLimitedError';
+        this.retryAfter = opts?.retryAfter;
+    }
+}
+/** Generic 5xx-after-retries failure. */
+export class TransientError extends DriveSyncError {
+    constructor(message = 'Transient upstream error', opts) {
+        super(message, opts);
+        this.name = 'TransientError';
+    }
+}
+/** 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') {
+        super(message);
+        this.name = 'GisLoadError';
+    }
+}

package/dist/files.d.ts

@@ -0,0 +1,70 @@
+import type { Logger } from './logger.js';
+import type { FileRef } from './types.js';
+/** Scopes this library always requests/requires. */
+export declare const REQUIRED_SCOPES: string[];
+interface BaseCallOptions {
+    appId: string;
+    projectId: string;
+    clientId: string;
+    interactive?: boolean;
+    logger?: Logger;
+    fetchEmail?: (accessToken: string) => Promise<string>;
+}
+export interface ReadOptions extends BaseCallOptions {
+    fileId: string;
+}
+/**
+ * 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
+ * connected account cannot see — this ambiguity is documented in the public
+ * API and callers are expected to treat `null` as "not available" rather
+ * than distinguishing the two cases.
+ */
+export declare function read(opts: ReadOptions): Promise<string | Blob | null>;
+export interface RemoveOptions extends BaseCallOptions {
+    fileId: string;
+}
+export declare function remove(opts: RemoveOptions): Promise<void>;
+export interface WriteOptions extends BaseCallOptions {
+    fileId?: string;
+    folderId?: string;
+    name?: string;
+    content: string | Blob;
+    mimeType: string;
+}
+/**
+ * Creates or updates a file's content. Updates (fileId provided) use the
+ * media-upload endpoint with the raw body. Creates use a `FormData`
+ * multipart body — FormData + fetch computes and inserts its own boundary,
+ * 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).
+ */
+export declare function write(opts: WriteOptions): Promise<FileRef>;
+export interface ListOptions extends BaseCallOptions {
+    folderId?: string;
+    mimeType?: string;
+    nameEquals?: string;
+}
+export declare function list(opts: ListOptions): Promise<FileRef[]>;
+export interface EnsureFolderPathOptions extends BaseCallOptions {
+    folderPath: string[];
+}
+/**
+ * Walks `folderPath` level by level, creating any missing folder along the
+ * way, and returns the leaf folder's id (never persisted by this library —
+ * callers get it fresh on every call).
+ *
+ * Root-level (first path segment) lookup design choice: Drive's "My Drive"
+ * root has no single well-known parent id that is safe to assume across
+ * every account/Shared-Drive configuration, and this library only has the
+ * `drive.file` scope (which only sees files/folders the app itself created
+ * or that were explicitly shared with it) — so instead of trying to anchor
+ * the first level under an assumed parent, we search WITHOUT a `... in
+ * parents` clause for the first level (`mimeType='...folder' and name='...'
+ * and trashed=false`), which finds the folder anywhere this app can see it.
+ * Every subsequent level uses the previous level's resolved id as an
+ * explicit `in parents` clause, which is unambiguous.
+ */
+export declare function ensureFolderPath(opts: EnsureFolderPathOptions): Promise<string>;
+export {};