@open-webapp/drive-sync 0.7.1 → 0.8.0

package/README.md

@@ -38,6 +38,22 @@ const ref = await p.files.update(fileId, {
 })
 ```
 
+### Synchronous connection snapshot
+
+`p.getConnectionSync()` / `p.subscribeConnection()` give a framework store a
+synchronous, referentially-stable `Connection | null` without polling:
+
+```ts
+const store = {
+  get: () => p.getConnectionSync(),
+  subscribe: (onChange: () => void) => p.subscribeConnection(onChange),
+}
+```
+
+This pairing is the intended backing for `@open-webapp/drive-connect`'s React
+hook (`useDriveConnection`), and works equally well for any other
+`useSyncExternalStore`-shaped store.
+
 See `SPEC.md` for the full design: the 36 resolved decisions, storage layout,
 and refresh state machine. `SPEC.md` is descriptive, written from the shipped
 code — if it ever disagrees with the source, the source wins.

package/SPEC.md

@@ -30,6 +30,8 @@ await drive.reconcile(knownProjectIds);          // drop orphaned per-project au
 const p = drive.project(projectId);
 await p.connect();                               // interactive; prompt:'consent'
 const conn = await p.getConnection();            // { email, needsReauth, expiresAt } | null
+const snap = p.getConnectionSync();            // Connection | null, synchronous, referentially stable
+const unsub = p.subscribeConnection(() => {}); // fires when the snapshot reference changes
 
 const picked = await p.pickFile({ apiKey: PICKER_API_KEY, appId: GCP_PROJECT_NUMBER });  // file-selection via Google Picker
 const folderId = await p.ensureFolderPath();
@@ -46,10 +48,27 @@ dispose();
 
 `createDriveSync()` itself attaches no listeners and makes no network calls. Every Drive-op call site accepts an optional `{ interactive?: boolean }` (default `false`) and resolves its own token internally — no caller ever threads a token or a `projectId` string into an HTTP call by hand.
 
-Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHandle`/`PermissionsHandle`), `connection.ts` (`connect`/`getConnection`/`disconnect`/`refreshSilently`/`getAccessToken`), `files.ts`, `permissions.ts`, `reconcile.ts`, `refresh.ts` (`activate`/warm-up), `picker.ts` (Google Picker integration), `errors.ts` (typed error classes), `types.ts` (`DriveSyncOptions`, `Connection`, `StoredToken`, `FileRef`, `DrivePermission`, `CallOptions`).
+Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHandle`/`PermissionsHandle`, plus `getConnectionSync`/`subscribeConnection`), `connection.ts` (`connect`/`getConnection`/`disconnect`/`refreshSilently`/`getAccessToken`), `files.ts`, `permissions.ts`, `reconcile.ts`, `refresh.ts` (`activate`/warm-up), `picker.ts` (Google Picker integration), `errors.ts` (typed error classes), `types.ts` (`DriveSyncOptions`, `Connection`, `StoredToken`, `FileRef`, `DrivePermission`, `CallOptions`).
 
 `getAccessToken()` is the one deliberate exception to `Connection` never exposing secret material (types.ts): it exists solely so an app can feed the token to Google Picker (`setOAuthToken()`), which runs outside this library's control and has no other way to read it. Reuses a cached token while it has more than 5 minutes left; otherwise acquires one (interactive by default, since callers use this to drive a UI the user is actively interacting with).
 
+### Connection snapshot
+
+`index.ts` holds one in-memory `Connection | null` per `projectId`, in a `snapshotStores` Map inside the `createDriveSync` closure (alongside `trackedProjectIds`) — one `ConnectionSnapshotStore` (`connectionSnapshot.ts`) per project, created lazily on first access. Each store shallow-compares the incoming `Connection` on `email`/`needsReauth`/`expiresAt` before replacing its held reference, so `get()` returns a referentially-stable value suitable for `useSyncExternalStore`.
+
+`null` from `getConnectionSync()` is ambiguous by design: it means either "disconnected" or "not yet hydrated" (the first background re-read from IndexedDB hasn't resolved). Callers cannot distinguish the two from the return value alone.
+
+The snapshot is (re-)read from IndexedDB via `getConnection()` in several places, all but one of them fire-and-forget:
+
+- **Lazily, on first access** — the first call to `getConnectionSync()` or `subscribeConnection()` for a project kicks off a `void`-ed re-read.
+- **On a background warm-up** — `refresh.ts`'s `warmUpIfNeeded`, run from `activate()`'s `visibilitychange`/`pageshow` handlers.
+- **On a cross-tab `logout`/`token` broadcast** — `handleBroadcast` re-reads the snapshot for the affected project. This only fires while `activate()` has been called (broadcast listening starts there).
+- **For every tracked project, at `activate()` itself** — so already-registered projects get an immediate re-read when activation starts.
+
+**The one exception:** after `connect()`/`disconnect()`, the re-read is `await`ed *before* the call resolves. This is the one place callers can rely on synchronous-after-await freshness — the moment `await p.connect()` (or `disconnect()`) returns, `p.getConnectionSync()` already reflects the new state. Every other re-read above is intentionally fire-and-forget, since nothing is awaiting them to observe the snapshot synchronously.
+
+One behavioral consequence worth calling out: because the broadcast handler re-reads on `logout`, a `disconnect()` in one tab becomes observable to `subscribeConnection()` listeners in every other open tab — a capability the async-only `getConnection()` never had (nothing pushes to it).
+
 ## 2. The 41 resolved design decisions
 
 **Bugs fixed (both source apps carried these):**
@@ -109,6 +128,8 @@ Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHand
 
 42. **`list()` passes through `thumbnailLink` + `imageMediaMetadata`, unfiltered and verbatim** — `files.ts`'s `list()` extends the same `fields` mask touched in #36's `modifiedTime` change to also request `thumbnailLink` and `imageMediaMetadata(width,height,rotation)`; `FileRef` (`types.ts`) gains three optional fields — `mimeType?` (already fetched, previously just untyped), `thumbnailLink?`, and `imageMediaMetadata?: { width?; height?; rotation? }` — all `fields`-gated and may be absent on older or partial responses. `list()` stays unfiltered: it returns every file of any MIME type with no `image/` check and no opt-in flag, and `thumbnailLink` is passed through exactly as Drive returns it — no blob fetch, no URL rewrite, no `=s220` size munging, and no `files.thumbnail()` helper. Caveat: `thumbnailLink` is a short-lived URL (good for only ~hours) that can require the browser to be carrying Google auth context for the file's owning account, so a cross-origin bare `<img src>` may 403; rendering is the consuming app's responsibility, and it can fall back to `getAccessToken()` + fetch-to-blob itself. (Label is `42` though this is only the 41st entry — the section carries a duplicate `7.` label and a merged `25–27.` entry, so the labels have always run one ahead of the item count; no existing entry is renumbered.)
 
+43. **Synchronous connection snapshot, per project** — `index.ts`'s `ProjectHandle` gains `getConnectionSync(): Connection | null` and `subscribeConnection(cb): () => void`, backed by a new `connectionSnapshot.ts` (`createConnectionSnapshotStore`) held per `projectId` in the `snapshotStores` Map alongside `trackedProjectIds`. The store shallow-compares `email`/`needsReauth`/`expiresAt` so its reference stays stable across no-op re-reads (`useSyncExternalStore`-friendly). It is populated lazily on first access, kept warm by the same warm-up/broadcast/`activate()` paths that already existed, and — the one synchronous-after-await guarantee in the package — re-read and `await`ed to completion inside `connect()`/`disconnect()` before those calls resolve. A side effect: cross-tab `logout` broadcasts now push a visible state change to `subscribeConnection()` listeners, which the async-only `getConnection()` never did.
+
 ## 3. Storage layout
 
 Each project gets its own IndexedDB database: **`owa-drive-{appId}-{projectId}`**, version 1, containing one object store, `auth` (`storage.ts`). The store holds up to three keys (`conn`/`token` always; `envelope` only in server-facilitated token-exchange mode):

package/dist/connectionSnapshot.d.ts

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

package/dist/connectionSnapshot.js

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

package/dist/index.d.ts

@@ -58,6 +58,20 @@ export interface ProjectHandle {
      */
     getAccessToken(callOpts?: CallOptions): Promise<string>;
     pickFile(options: PickFileOptions): Promise<PickedFile[]>;
+    /**
+     * Synchronous snapshot of the current Connection, backed by the
+     * per-project connectionSnapshot store (see connectionSnapshot.ts).
+     * Never returns a Promise and never throws. `null` means either
+     * disconnected, or not-yet-hydrated (the first background re-read from
+     * IndexedDB hasn't resolved yet) — callers cannot distinguish the two
+     * from this alone.
+     */
+    getConnectionSync(): Connection | null;
+    /**
+     * Subscribes to changes in the synchronous Connection snapshot (suitable
+     * for `useSyncExternalStore`). Returns an unsubscribe function.
+     */
+    subscribeConnection(cb: () => void): () => void;
     files: FilesHandle;
     permissions: PermissionsHandle;
 }

package/dist/index.js

@@ -6,6 +6,7 @@ import * as permissionsImpl from './permissions.js';
 import * as pickerImpl from './picker.js';
 import { warmUpIfNeeded } from './refresh.js';
 import { REQUIRED_SCOPES } from './files.js';
+import { createConnectionSnapshotStore } from './connectionSnapshot.js';
 import { createBroadcast } from './broadcast.js';
 import { evictDbHandle } from './storage.js';
 import { notifyExternalTokenRefresh } from './token.js';
@@ -68,6 +69,43 @@ export function createDriveSync(options) {
     function trackProject(projectId) {
         trackedProjectIds.add(projectId);
     }
+    /**
+     * Per-project synchronous Connection snapshot stores (see
+     * connectionSnapshot.ts). Populated lazily by `getOrInitStore` the first
+     * time either `getConnectionSync()` or `subscribeConnection()` is called
+     * for a given project; a later task (T3) will also commit into these
+     * stores after connect()/disconnect() resolve.
+     */
+    const snapshotStores = new Map();
+    /**
+     * Re-reads the durable Connection for `projectId` from IndexedDB (via
+     * connection.ts's `getConnection`) and commits the result into that
+     * project's snapshot store. Returns the underlying promise (rather than
+     * `void`-ing it here) so a LATER task (T3) can `await` it after
+     * connect()/disconnect(); call sites in THIS task fire it with `void`.
+     */
+    function reReadConnection(projectId) {
+        return getConnectionImpl({
+            appId,
+            projectId,
+            requiredScopes: REQUIRED_SCOPES,
+        })
+            .then((conn) => {
+            getOrInitStore(projectId).commit(conn);
+        })
+            .catch((err) => {
+            logger.warn('drive-sync: connection snapshot re-read failed', { err });
+        });
+    }
+    function getOrInitStore(projectId) {
+        let store = snapshotStores.get(projectId);
+        if (!store) {
+            store = createConnectionSnapshotStore();
+            snapshotStores.set(projectId, store);
+            void reReadConnection(projectId);
+        }
+        return store;
+    }
     /**
      * Handles a cross-tab broadcast (see broadcast.ts) received while active.
      * `logout`: another tab's disconnect() already cleared BOTH IndexedDB
@@ -87,19 +125,23 @@ export function createDriveSync(options) {
     function handleBroadcast(msg) {
         if (msg.type === 'logout') {
             void evictDbHandle(appId, msg.projectId);
+            reReadConnection(msg.projectId);
         }
         else if (msg.type === 'token') {
             notifyExternalTokenRefresh(msg.projectId);
+            reReadConnection(msg.projectId);
         }
     }
     function activate() {
         const disposeBroadcast = createBroadcast(appId).onMessage(handleBroadcast);
+        for (const projectId of trackedProjectIds)
+            reReadConnection(projectId);
         if (typeof document === 'undefined') {
             return disposeBroadcast;
         }
         const runWarmUps = () => {
             for (const projectId of trackedProjectIds) {
-                void warmUpIfNeeded({ appId, projectId, clientId, tokenExchangeUrl, fetchEmail, logger });
+                void warmUpIfNeeded({ appId, projectId, clientId, tokenExchangeUrl, fetchEmail, logger }).then(() => reReadConnection(projectId), () => reReadConnection(projectId));
             }
         };
         const onVisibilityChange = () => {
@@ -164,8 +206,8 @@ export function createDriveSync(options) {
             },
         };
         return {
-            connect() {
-                return connectImpl({
+            async connect() {
+                const connection = await connectImpl({
                     appId,
                     projectId,
                     clientId,
@@ -174,6 +216,15 @@ export function createDriveSync(options) {
                     logger,
                     fetchEmail,
                 });
+                // Awaited (not fire-and-forget): callers of `await connect()` must
+                // see `getConnectionSync()` already reflect this new connection the
+                // moment the promise settles — see reReadConnection's docstring.
+                // Contrast with warm-up/broadcast/lazy-kick re-reads elsewhere in
+                // this file, which are intentionally fire-and-forget (`void
+                // reReadConnection(...)`) since nothing is awaiting them to observe
+                // the snapshot synchronously.
+                await reReadConnection(projectId);
+                return connection;
             },
             getConnection() {
                 return getConnectionImpl({
@@ -201,6 +252,10 @@ export function createDriveSync(options) {
                     },
                 };
                 await disconnectImpl(disconnectOpts);
+                // Awaited, same reasoning as connect() above: `await disconnect()`
+                // must not settle until `getConnectionSync()` reflects the
+                // post-disconnect snapshot.
+                await reReadConnection(projectId);
             },
             ensureFolderPath() {
                 return filesImpl.ensureFolderPath({ ...base, folderPath });
@@ -245,6 +300,12 @@ export function createDriveSync(options) {
                 }
                 return results;
             },
+            getConnectionSync() {
+                return getOrInitStore(projectId).get();
+            },
+            subscribeConnection(cb) {
+                return getOrInitStore(projectId).subscribe(cb);
+            },
             files,
             permissions,
         };

package/package.json

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