@open-webapp/drive-sync 0.1.0 → 0.3.0

package/dist/picker.d.ts

@@ -0,0 +1,95 @@
+import type { WorkspaceMimeShorthand } from './types.js';
+/**
+ * Minimal ambient type declarations for Google Picker and GIS APIs.
+ * These allow TypeScript to recognize window.gapi and window.google.picker
+ * without importing the actual Google libraries.
+ */
+declare global {
+    interface Window {
+        gapi?: {
+            load(api: string, callback: () => void): void;
+        };
+        google?: {
+            picker?: {
+                PickerBuilder: new (...args: any[]) => PickerBuilder;
+                DocsView: new (...args: any[]) => DocsView;
+                Action: {
+                    PICKED: string;
+                    CANCEL: string;
+                };
+                ViewId: {
+                    DOCS: string;
+                };
+                Feature: {
+                    MULTISELECT_ENABLED: string;
+                };
+            };
+        };
+    }
+}
+interface PickerBuilder {
+    addView(view: DocsView): PickerBuilder;
+    setOAuthToken(token: string): PickerBuilder;
+    setDeveloperKey(key: string): PickerBuilder;
+    setAppId(appId: string): PickerBuilder;
+    enableFeature(feature: string): PickerBuilder;
+    setCallback(callback: (data: PickerResponse) => void): PickerBuilder;
+    build(): PickerInstance;
+}
+interface DocsView {
+    setMimeTypes(types: string): DocsView;
+    setParent(folderId: string): DocsView;
+}
+interface PickerInstance {
+    setVisible(visible: boolean): void;
+}
+interface PickerResponse {
+    action?: string;
+    docs?: PickerDocument[];
+}
+interface PickerDocument {
+    id: string;
+    name: string;
+    mimeType: string;
+}
+/**
+ * Test-only export: resets the script load cache, allowing tests to
+ * re-inject or mock the picker script. Exported normally (not conditionally gated)
+ * so tests can import and call it directly.
+ */
+export declare function __resetPickerScriptCacheForTests(): void;
+export interface OpenPickerOptions {
+    apiKey: string;
+    oauthToken: string;
+    /**
+     * The Cloud project *number* of the OAuth client that minted `oauthToken`.
+     * Required: this library requests only the `drive.file` scope, and Picker
+     * refuses to run a scoped session it cannot attribute to an app. Omit it and
+     * Picker discards the OAuth token, falls back to its own sign-in prompt, and
+     * then fails the unauthenticated developer-key check with "The API developer
+     * key is invalid" — even though the key and its referrer restrictions are fine.
+     */
+    appId: string;
+    mimeTypes?: (string | WorkspaceMimeShorthand)[];
+    multiSelect?: boolean;
+    parentFolderId?: string;
+}
+export interface PickedFile {
+    fileId: string;
+    name: string;
+    mimeType: string;
+}
+/**
+ * Opens the Google Picker dialog for file selection, returning a promise
+ * that resolves with the selected files or rejects if the user cancels.
+ *
+ * The picker is configured with optional MIME type filters, multi-select
+ * support, and a parent folder constraint.
+ *
+ * @param opts - Configuration including API key, OAuth token, and picker options
+ * @returns Promise resolving to an array of picked files
+ * @throws PickerCancelledError if the user cancels the dialog
+ * @throws Error if the Picker script fails to load or configuration fails
+ */
+export declare function openPicker(opts: OpenPickerOptions): Promise<PickedFile[]>;
+export {};

package/dist/picker.js

@@ -0,0 +1,140 @@
+import { PickerCancelledError } from './errors.js';
+/**
+ * Maps Google Workspace document type shorthands to their full MIME types.
+ */
+const WORKSPACE_MIME_SHORTHAND = {
+    docs: 'application/vnd.google-apps.document',
+    sheets: 'application/vnd.google-apps.spreadsheet',
+    slides: 'application/vnd.google-apps.presentation',
+    forms: 'application/vnd.google-apps.form',
+    drawings: 'application/vnd.google-apps.drawing',
+};
+/**
+ * Module-level cache for the Picker script loading promise.
+ * Reused across multiple openPicker() calls to avoid re-injecting the script.
+ */
+let scriptLoadPromise = null;
+/**
+ * Resolves an optional array of MIME types, expanding shorthand tokens
+ * (e.g., 'docs', 'sheets') to their full `application/vnd.google-apps.*` equivalents
+ * and passing literal MIME strings through unchanged.
+ *
+ * @param mimeTypes - Array containing strings and/or WorkspaceMimeShorthand tokens
+ * @returns Expanded array of MIME type strings, or undefined if input is undefined
+ */
+function resolveMimeTypes(mimeTypes) {
+    if (!mimeTypes) {
+        return undefined;
+    }
+    return mimeTypes.map((type) => {
+        if (type in WORKSPACE_MIME_SHORTHAND) {
+            return WORKSPACE_MIME_SHORTHAND[type];
+        }
+        return type;
+    });
+}
+/**
+ * Ensures the Google Picker API is loaded by:
+ * 1. Checking if window.google.picker already exists (e.g., from a test fake)
+ * 2. Reusing a pending script load if one is already in progress
+ * 3. Otherwise, injecting the picker script and waiting for gapi.load('picker')
+ *
+ * On script error, resets the cache so a retry will re-inject.
+ *
+ * @throws Error if script load fails
+ */
+async function ensurePickerLoaded() {
+    // Already loaded (e.g., by a test fake or prior successful load)
+    if (window.google?.picker) {
+        return;
+    }
+    // Script load already in progress; reuse the existing promise
+    if (scriptLoadPromise) {
+        return scriptLoadPromise;
+    }
+    // Inject the Picker script and set up the load promise
+    scriptLoadPromise = new Promise((resolve, reject) => {
+        const script = document.createElement('script');
+        script.src = 'https://apis.google.com/js/api.js';
+        script.onload = () => {
+            // Script loaded; now request the Picker API
+            window.gapi.load('picker', () => {
+                resolve();
+            });
+        };
+        script.onerror = () => {
+            // Script failed to load; reset cache so retry can re-inject
+            scriptLoadPromise = null;
+            reject(new Error('Failed to load Google Picker script'));
+        };
+        document.head.appendChild(script);
+    });
+    return scriptLoadPromise;
+}
+/**
+ * Test-only export: resets the script load cache, allowing tests to
+ * re-inject or mock the picker script. Exported normally (not conditionally gated)
+ * so tests can import and call it directly.
+ */
+export function __resetPickerScriptCacheForTests() {
+    scriptLoadPromise = null;
+}
+/**
+ * Opens the Google Picker dialog for file selection, returning a promise
+ * that resolves with the selected files or rejects if the user cancels.
+ *
+ * The picker is configured with optional MIME type filters, multi-select
+ * support, and a parent folder constraint.
+ *
+ * @param opts - Configuration including API key, OAuth token, and picker options
+ * @returns Promise resolving to an array of picked files
+ * @throws PickerCancelledError if the user cancels the dialog
+ * @throws Error if the Picker script fails to load or configuration fails
+ */
+export async function openPicker(opts) {
+    // Ensure the Picker API is available
+    await ensurePickerLoaded();
+    // Create and configure a DocsView for file browsing
+    const docsView = new window.google.picker.DocsView();
+    // Apply MIME type filters if provided
+    const resolvedMimes = resolveMimeTypes(opts.mimeTypes);
+    if (resolvedMimes) {
+        docsView.setMimeTypes(resolvedMimes.join(','));
+    }
+    // Constrain to a specific parent folder if provided
+    if (opts.parentFolderId) {
+        docsView.setParent(opts.parentFolderId);
+    }
+    // Create and configure the PickerBuilder
+    const pickerBuilder = new window.google.picker.PickerBuilder();
+    pickerBuilder
+        .addView(docsView)
+        .setOAuthToken(opts.oauthToken)
+        .setDeveloperKey(opts.apiKey)
+        .setAppId(opts.appId);
+    // Enable multi-select if requested
+    if (opts.multiSelect) {
+        pickerBuilder.enableFeature(window.google.picker.Feature.MULTISELECT_ENABLED);
+    }
+    // Set up the response handler and build the picker
+    return new Promise((resolve, reject) => {
+        pickerBuilder.setCallback((data) => {
+            // User picked files
+            if (data.action === window.google.picker.Action.PICKED && data.docs) {
+                const picked = data.docs.map((doc) => ({
+                    fileId: doc.id,
+                    name: doc.name,
+                    mimeType: doc.mimeType,
+                }));
+                resolve(picked);
+                return;
+            }
+            // User cancelled
+            if (data.action === window.google.picker.Action.CANCEL) {
+                reject(new PickerCancelledError());
+                return;
+            }
+        });
+        pickerBuilder.build().setVisible(true);
+    });
+}

package/dist/storage.d.ts

@@ -6,10 +6,21 @@ export interface ConnRecord {
     grantedScopes: string[];
     connectedAt: number;
 }
+/**
+ * Per-file sync baseline: the Drive `version` this client last restored (via
+ * files.read()) or last successfully wrote. A write is only allowed when the
+ * file's current remote version still matches this — see files.ts.
+ */
+export interface FileStateRecord {
+    fileId: string;
+    version: string;
+    /** Epoch ms at which this baseline was recorded. */
+    syncedAt: number;
+}
 interface AuthDbSchema extends DBSchema {
     auth: {
         key: string;
-        value: ConnRecord | StoredToken;
+        value: ConnRecord | StoredToken | FileStateRecord;
     };
 }
 export declare function openAuthDb(appId: string, projectId: string): Promise<IDBPDatabase<AuthDbSchema>>;
@@ -24,4 +35,7 @@ export declare function clearConn(appId: string, projectId: string): Promise<voi
 export declare function getToken(appId: string, projectId: string): Promise<StoredToken | undefined>;
 export declare function setToken(appId: string, projectId: string, token: StoredToken): Promise<void>;
 export declare function clearToken(appId: string, projectId: string): Promise<void>;
+export declare function getFileState(appId: string, projectId: string, fileId: string): Promise<FileStateRecord | undefined>;
+export declare function setFileState(appId: string, projectId: string, state: FileStateRecord): Promise<void>;
+export declare function clearFileState(appId: string, projectId: string, fileId: string): Promise<void>;
 export {};

package/dist/storage.js

@@ -2,6 +2,18 @@ import { openDB } from 'idb';
 const AUTH_STORE = 'auth';
 const CONN_KEY = 'conn';
 const TOKEN_KEY = 'token';
+/**
+ * File baselines live in the existing 'auth' store under a namespaced key
+ * rather than in a store of their own, deliberately: adding a store means
+ * bumping the DB version, and an upgrade cannot run while ANY other
+ * connection still holds the old version open. Older tabs run older code
+ * that has no way to know it should close, so the upgrade would block
+ * indefinitely and every Drive call — which needs this DB for its token —
+ * would hang rather than fail. Keeping the schema at v1 avoids that entirely.
+ */
+function fileKey(fileId) {
+    return `file:${fileId}`;
+}
 function dbName(appId, projectId) {
     return `owa-drive-${appId}-${projectId}`;
 }
@@ -19,6 +31,11 @@ export function openAuthDb(appId, projectId) {
                     db.createObjectStore(AUTH_STORE);
                 }
             },
+            // Defence for any FUTURE version bump: close this connection as soon as
+            // another tab needs to upgrade, so it is never the thing blocking.
+            blocking() {
+                void evictDbHandle(appId, projectId);
+            },
         });
         dbCache.set(key, handle);
     }
@@ -68,3 +85,16 @@ export async function clearToken(appId, projectId) {
     const db = await openAuthDb(appId, projectId);
     await db.delete(AUTH_STORE, TOKEN_KEY);
 }
+export async function getFileState(appId, projectId, fileId) {
+    const db = await openAuthDb(appId, projectId);
+    const value = await db.get(AUTH_STORE, fileKey(fileId));
+    return value;
+}
+export async function setFileState(appId, projectId, state) {
+    const db = await openAuthDb(appId, projectId);
+    await db.put(AUTH_STORE, state, fileKey(state.fileId));
+}
+export async function clearFileState(appId, projectId, fileId) {
+    const db = await openAuthDb(appId, projectId);
+    await db.delete(AUTH_STORE, fileKey(fileId));
+}

package/dist/testing/driveFake.d.ts

@@ -20,6 +20,11 @@ export interface DriveFakeFile {
     content: string;
     contentType?: string;
     trashed?: boolean;
+    /**
+     * Drive's monotonic per-file change counter, bumped on every mutation.
+     * Optional so tests may seed files without it; treated as 1 when absent.
+     */
+    version?: number;
 }
 export interface DriveFakePermission {
     id: string;
@@ -44,6 +49,11 @@ export interface DriveFake {
     reset(): void;
     /** Inspect current in-memory files, keyed by id. */
     readonly files: Map<string, DriveFakeFile>;
+    /**
+     * Simulate another client editing the file: replaces content and bumps
+     * `version`, exactly as a real out-of-band Drive write would.
+     */
+    externalEdit(fileId: string, content: string): void;
     /** Inspect current in-memory permissions, keyed by fileId then permission id. */
     readonly permissions: Map<string, Map<string, DriveFakePermission>>;
 }

package/dist/testing/driveFake.js

@@ -142,7 +142,7 @@ export function createDriveFake() {
         return override;
     }
     function fileToMetadata(f) {
-        return { id: f.id, name: f.name, mimeType: f.mimeType, parents: f.parents };
+        return { id: f.id, name: f.name, mimeType: f.mimeType, parents: f.parents, version: String(f.version ?? 1) };
     }
     async function handleFilesList(url) {
         const q = url.searchParams.get('q') ?? '';
@@ -218,6 +218,7 @@ export function createDriveFake() {
             parents: Array.isArray(metadata.parents) ? metadata.parents : [],
             content,
             contentType: mediaType,
+            version: 1,
         };
         files.set(id, file);
         if (mimeType === FOLDER_MIME_TYPE) {
@@ -237,6 +238,7 @@ export function createDriveFake() {
             const contentType = getHeader(init, 'Content-Type');
             if (contentType)
                 file.contentType = contentType;
+            file.version = (file.version ?? 1) + 1;
             return jsonResponse(fileToMetadata(file));
         }
         if (uploadType === 'multipart') {
@@ -254,6 +256,7 @@ export function createDriveFake() {
                 file.content = parsed.mediaContent;
                 if (parsed.mediaType)
                     file.contentType = parsed.mediaType;
+                file.version = (file.version ?? 1) + 1;
             }
             return jsonResponse(fileToMetadata(file));
         }
@@ -285,6 +288,7 @@ export function createDriveFake() {
             const removeSet = new Set(removeParents.split(','));
             file.parents = file.parents.filter((p) => !removeSet.has(p));
         }
+        file.version = (file.version ?? 1) + 1;
         return jsonResponse(fileToMetadata(file));
     }
     async function handleFileDelete(id) {
@@ -411,6 +415,13 @@ export function createDriveFake() {
                 remaining: opts?.times ?? 1,
             });
         },
+        externalEdit(fileId, content) {
+            const file = files.get(fileId);
+            if (!file)
+                throw new Error(`driveFake.externalEdit: unknown file ${fileId}`);
+            file.content = content;
+            file.version = (file.version ?? 1) + 1;
+        },
         reset() {
             files.clear();
             permissions.clear();

package/dist/testing/gisFake.d.ts

@@ -50,6 +50,12 @@ export interface GisFake {
     calls: GisRecordedCall[];
     /** Queue a response to be delivered to the next `requestAccessToken` call. */
     queueResponse(response: GisTokenResponse): void;
+    /**
+     * Queue a popup-level failure for the next `requestAccessToken` call,
+     * delivered via `error_callback` — the channel the real GIS client uses
+     * for a blocked or dismissed popup, which never reaches `callback`.
+     */
+    queuePopupError(type: string): void;
     /** Stub `window.google.accounts.oauth2.initTokenClient` with this fake. */
     install(): void;
     /** Remove the stub installed by `install()`, restoring prior state. */

package/dist/testing/gisFake.js

@@ -15,6 +15,7 @@
  */
 export function createGisFake() {
     const responseQueue = [];
+    const popupErrorQueue = [];
     const calls = [];
     let previousGoogle;
     let hadGoogle = false;
@@ -32,6 +33,14 @@ export function createGisFake() {
                 const hint = overrideConfig?.hint ?? config.hint;
                 const scope = overrideConfig?.scope ?? config.scope ?? '';
                 calls.push({ prompt, hint, scope });
+                const popupError = popupErrorQueue.shift();
+                if (popupError) {
+                    const errorCallback = config.error_callback;
+                    queueMicrotask(() => {
+                        errorCallback?.({ type: popupError });
+                    });
+                    return;
+                }
                 const response = nextResponse();
                 const callback = config.callback;
                 // Deliver asynchronously (microtask), matching the real GIS client's
@@ -54,6 +63,9 @@ export function createGisFake() {
         queueResponse(response) {
             responseQueue.push(response);
         },
+        queuePopupError(type) {
+            popupErrorQueue.push(type);
+        },
         install() {
             const w = globalThis;
             hadGoogle = Object.prototype.hasOwnProperty.call(w, 'google');
@@ -80,6 +92,7 @@ export function createGisFake() {
         },
         reset() {
             responseQueue.length = 0;
+            popupErrorQueue.length = 0;
             calls.length = 0;
         },
     };

package/dist/testing/index.d.ts

@@ -2,3 +2,5 @@ export { createGisFake } from './gisFake.js';
 export type { GisFake, GisTokenResponse, GisRecordedCall } from './gisFake.js';
 export { createDriveFake } from './driveFake.js';
 export type { DriveFake, DriveFakeFile, DriveFakePermission, StatusOverrideOptions } from './driveFake.js';
+export { createPickerFake } from './pickerFake.js';
+export type { PickerFake, PickerFakeFile, PickerRecordedCall } from './pickerFake.js';

package/dist/testing/index.js

@@ -1,2 +1,3 @@
 export { createGisFake } from './gisFake.js';
 export { createDriveFake } from './driveFake.js';
+export { createPickerFake } from './pickerFake.js';

package/dist/testing/pickerFake.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A scriptable double for Google Picker (google.picker),
+ * for use in tests of code that calls `window.google.picker.PickerBuilder`
+ * and related APIs.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const pickerFake = createPickerFake()
+ * pickerFake.install()
+ * // ... exercise code under test that calls openPicker() ...
+ * pickerFake.simulatePick([{ fileId: '123', name: 'doc.txt', mimeType: 'text/plain' }])
+ * await expect(openPickerPromise).resolves.toEqual([...])
+ * expect(pickerFake.calls).toHaveLength(1)
+ * ```
+ */
+export interface PickerFakeFile {
+    fileId: string;
+    name: string;
+    mimeType: string;
+}
+export interface PickerRecordedCall {
+    oauthToken?: string;
+    developerKey?: string;
+    appId?: string;
+    views: Array<{
+        mimeTypes?: string;
+        parentId?: string;
+    }>;
+    features: string[];
+}
+export interface PickerFake {
+    /** All PickerBuilder constructions and their configurations, in order. */
+    calls: PickerRecordedCall[];
+    /** Simulate user picking files; invokes the picker's callback asynchronously. */
+    simulatePick(files: PickerFakeFile[]): void;
+    /** Simulate user cancelling; invokes the picker's callback asynchronously. */
+    simulateCancel(): void;
+    /** Stub window.gapi and window.google.picker with this fake. */
+    install(): void;
+    /** Remove the stub installed by `install()`, restoring prior state. */
+    uninstall(): void;
+    /** Clear call history and stored callback state. */
+    reset(): void;
+}
+export declare function createPickerFake(): PickerFake;