@open-webapp/drive-sync 0.6.0 → 0.7.0

package/SPEC.md

@@ -50,7 +50,7 @@ Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHand
 
 `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 36 resolved design decisions
+## 2. The 41 resolved design decisions
 
 **Bugs fixed (both source apps carried these):**
 
@@ -107,6 +107,8 @@ Files implementing the surface: `index.ts` (factory + `ProjectHandle`/`FilesHand
 
 41. **Envelope error mapping, opaque `sig`, no schema bump** — `envelope.ts` maps exchange failures onto typed reauth reasons: `410` → clear conn+token+envelope, then `NeedsReauthError` (`reason: 'refresh_token_revoked'`, surfaced internally as the distinguishable `EnvelopeRevokedError` subclass); `502` / other `5xx` / network throw / unparseable body → up to two retries (500ms, 1500ms) then `NeedsReauthError` (`reason: 'exchange_unavailable'`); other non-2xx (`400`/`401`/`404`/`403`/`409`) → `NeedsReauthError` (`reason: 'exchange_failed'`), no retry. The envelope's `sig` is a server signature that is **never** verified client-side — the structure is treated as fully opaque and only `payload` is read. The `envelope` key is added to the existing `auth` store with **no IndexedDB version bump** (still version 1).
 
+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.)
+
 ## 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/files.js

@@ -302,8 +302,10 @@ export async function list(opts) {
     // `version` comes back so the name-resolution path in write() can run its
     // staleness check without a follow-up metadata fetch. `modifiedTime` is
     // also requested so callers can get a last-modified timestamp per file
-    // without an extra round trip.
-    const url = `${DRIVE_BASE}/files?q=${encodeURIComponent(q)}&fields=${encodeURIComponent('files(id,name,mimeType,version,modifiedTime)')}`;
+    // without an extra round trip. `thumbnailLink` +
+    // `imageMediaMetadata(width,height,rotation)` are also requested so callers
+    // can render/orient low-res image thumbnails without an extra round trip.
+    const url = `${DRIVE_BASE}/files?q=${encodeURIComponent(q)}&fields=${encodeURIComponent('files(id,name,mimeType,version,modifiedTime,thumbnailLink,imageMediaMetadata(width,height,rotation))')}`;
     const res = await driveFetch({
         appId: opts.appId,
         projectId: opts.projectId,

package/dist/testing/driveFake.d.ts

@@ -31,6 +31,22 @@ export interface DriveFakeFile {
      * real Drive's `fields`-gated behavior).
      */
     modifiedTime?: string;
+    /**
+     * Drive's CDN thumbnail URL; optional so tests may seed files without it
+     * (omitted from the fake's response in that case, matching real Drive's
+     * `fields`-gated behavior).
+     */
+    thumbnailLink?: string;
+    /**
+     * Drive's image metadata (dimensions/rotation); optional so tests may seed
+     * files without it (omitted from the fake's response in that case, matching
+     * real Drive's `fields`-gated behavior).
+     */
+    imageMediaMetadata?: {
+        width?: number;
+        height?: number;
+        rotation?: number;
+    };
 }
 export interface DriveFakePermission {
     id: string;

package/dist/testing/driveFake.js

@@ -149,6 +149,8 @@ export function createDriveFake() {
             parents: f.parents,
             version: String(f.version ?? 1),
             modifiedTime: f.modifiedTime,
+            thumbnailLink: f.thumbnailLink,
+            imageMediaMetadata: f.imageMediaMetadata,
         };
     }
     async function handleFilesList(url) {

package/dist/types.d.ts

@@ -59,6 +59,16 @@ export interface FileRef {
     version?: string;
     /** Drive's last-modified timestamp (RFC3339), when the call requested it. */
     modifiedTime?: string;
+    /** Drive MIME type, when the call requested it. */
+    mimeType?: string;
+    /** Short-lived Drive thumbnail URL, when the call requested it and Drive supplied one; may be absent. */
+    thumbnailLink?: string;
+    /** Pixel dimensions (+ `rotation`, 0/90/180/270) for image files, when Drive supplied them. */
+    imageMediaMetadata?: {
+        width?: number;
+        height?: number;
+        rotation?: number;
+    };
 }
 /**
  * Sync state of one file relative to what this client last restored.

package/package.json

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