@open-webapp/drive-sync 0.6.0 → 0.7.1

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

@@ -221,13 +221,19 @@ export async function write(opts) {
     // and inserts a correct multipart boundary (never hand-rolled by us) and
     // exposes the resulting `Content-Type: multipart/form-data; boundary=...`
     // header, which we then forward explicitly alongside the serialized body.
-    // This also makes the request body a plain string by the time it reaches
-    // driveFetch, so environments (e.g. test fakes) that read the body via
-    // `.text()` rather than re-driving a real network stack see the fully
-    // encoded multipart payload rather than an opaque FormData object.
+    // This also makes the request body a concrete buffer by the time it reaches
+    // driveFetch, so environments (e.g. test fakes) that read the body without
+    // re-driving a real network stack see the fully encoded multipart payload
+    // rather than an opaque FormData object.
+    //
+    // The body is forwarded as an ArrayBuffer, never a string: a multipart body
+    // that carries a binary media part (a pasted PNG/JPEG) is not valid UTF-8,
+    // so `serialized.text()` would replace every non-UTF-8 byte with U+FFFD and
+    // fetch would then re-encode that lossy string, storing a corrupted blob on
+    // Drive. `arrayBuffer()` preserves the bytes exactly.
     const serialized = new Request('https://example.invalid/', { method: 'POST', body: form });
     const multipartContentType = serialized.headers.get('content-type') ?? undefined;
-    const multipartBody = await serialized.text();
+    const multipartBody = await serialized.arrayBuffer();
     const res = await driveFetch({
         appId: opts.appId,
         projectId: opts.projectId,
@@ -302,8 +308,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

@@ -105,7 +105,9 @@ async function readBodyText(init) {
         return '';
     if (typeof body === 'string')
         return body;
-    if (body instanceof Uint8Array)
+    if (body instanceof ArrayBuffer)
+        return new TextDecoder().decode(body);
+    if (ArrayBuffer.isView(body))
         return new TextDecoder().decode(body);
     if (typeof body.text === 'function')
         return await body.text();
@@ -149,6 +151,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.1",
   "type": "module",
   "repository": {
     "type": "git",