@open-webapp/drive-sync 0.1.0

package/dist/files.js

@@ -0,0 +1,231 @@
+import { driveFetch } from './http.js';
+import { escapeQ } from './query.js';
+import { NotFoundError } from './errors.js';
+const DRIVE_BASE = 'https://www.googleapis.com/drive/v3';
+const UPLOAD_BASE = 'https://www.googleapis.com/upload/drive/v3';
+const FOLDER_MIME_TYPE = 'application/vnd.google-apps.folder';
+/** Scopes this library always requests/requires. */
+export const REQUIRED_SCOPES = [
+    'https://www.googleapis.com/auth/drive.file',
+    'https://www.googleapis.com/auth/userinfo.email',
+];
+/**
+ * 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 async function read(opts) {
+    try {
+        const res = await driveFetch({
+            appId: opts.appId,
+            projectId: opts.projectId,
+            clientId: opts.clientId,
+            url: `${DRIVE_BASE}/files/${encodeURIComponent(opts.fileId)}?alt=media`,
+            method: 'GET',
+            interactive: opts.interactive,
+            requiredScopes: REQUIRED_SCOPES,
+            logger: opts.logger,
+            fetchEmail: opts.fetchEmail,
+        });
+        const contentType = res.headers.get('Content-Type') ?? '';
+        const isTextual = contentType === '' ||
+            contentType.startsWith('text/') ||
+            contentType.includes('application/json');
+        return isTextual ? await res.text() : await res.blob();
+    }
+    catch (err) {
+        if (err instanceof NotFoundError) {
+            return null;
+        }
+        throw err;
+    }
+}
+export async function remove(opts) {
+    await driveFetch({
+        appId: opts.appId,
+        projectId: opts.projectId,
+        clientId: opts.clientId,
+        url: `${DRIVE_BASE}/files/${encodeURIComponent(opts.fileId)}`,
+        method: 'DELETE',
+        interactive: opts.interactive,
+        requiredScopes: REQUIRED_SCOPES,
+        logger: opts.logger,
+        fetchEmail: opts.fetchEmail,
+    });
+}
+function toBlob(content, mimeType) {
+    return content instanceof Blob ? content : new Blob([content], { type: mimeType });
+}
+/**
+ * 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 async function write(opts) {
+    if (opts.fileId) {
+        const res = await driveFetch({
+            appId: opts.appId,
+            projectId: opts.projectId,
+            clientId: opts.clientId,
+            url: `${UPLOAD_BASE}/files/${encodeURIComponent(opts.fileId)}?uploadType=media`,
+            method: 'PATCH',
+            headers: { 'Content-Type': opts.mimeType },
+            body: opts.content,
+            interactive: opts.interactive,
+            requiredScopes: REQUIRED_SCOPES,
+            logger: opts.logger,
+            fetchEmail: opts.fetchEmail,
+        });
+        const json = (await res.json());
+        return { id: json.id, name: json.name ?? opts.name };
+    }
+    const metadata = {
+        name: opts.name,
+        mimeType: opts.mimeType,
+        parents: opts.folderId ? [opts.folderId] : undefined,
+    };
+    const form = new FormData();
+    form.append('metadata', new Blob([JSON.stringify(metadata)], { type: 'application/json' }));
+    form.append('media', toBlob(opts.content, opts.mimeType));
+    // Let the Fetch API's own Request serialize the FormData: this computes
+    // 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.
+    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 res = await driveFetch({
+        appId: opts.appId,
+        projectId: opts.projectId,
+        clientId: opts.clientId,
+        url: `${UPLOAD_BASE}/files?uploadType=multipart&fields=id`,
+        method: 'POST',
+        headers: multipartContentType ? { 'Content-Type': multipartContentType } : undefined,
+        body: multipartBody,
+        interactive: opts.interactive,
+        requiredScopes: REQUIRED_SCOPES,
+        logger: opts.logger,
+        fetchEmail: opts.fetchEmail,
+    });
+    const json = (await res.json());
+    return { id: json.id, name: opts.name };
+}
+function buildQuery(opts) {
+    const clauses = [];
+    if (opts.folderId) {
+        clauses.push(`'${escapeQ(opts.folderId)}' in parents`);
+    }
+    if (opts.mimeType) {
+        clauses.push(`mimeType='${escapeQ(opts.mimeType)}'`);
+    }
+    if (opts.nameEquals) {
+        clauses.push(`name='${escapeQ(opts.nameEquals)}'`);
+    }
+    clauses.push('trashed=false');
+    return clauses.join(' and ');
+}
+export async function list(opts) {
+    const q = buildQuery(opts);
+    const url = `${DRIVE_BASE}/files?q=${encodeURIComponent(q)}&fields=${encodeURIComponent('files(id,name,mimeType)')}`;
+    const res = await driveFetch({
+        appId: opts.appId,
+        projectId: opts.projectId,
+        clientId: opts.clientId,
+        url,
+        method: 'GET',
+        interactive: opts.interactive,
+        requiredScopes: REQUIRED_SCOPES,
+        logger: opts.logger,
+        fetchEmail: opts.fetchEmail,
+    });
+    const json = (await res.json());
+    return json.files ?? [];
+}
+/**
+ * Creates a plain-JSON folder (no content, so this goes through the
+ * non-upload /files endpoint) and returns its id.
+ */
+async function createFolder(opts) {
+    const res = await driveFetch({
+        appId: opts.appId,
+        projectId: opts.projectId,
+        clientId: opts.clientId,
+        url: `${DRIVE_BASE}/files?fields=id`,
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            name: opts.name,
+            mimeType: FOLDER_MIME_TYPE,
+            parents: opts.parentId ? [opts.parentId] : undefined,
+        }),
+        interactive: opts.interactive,
+        requiredScopes: REQUIRED_SCOPES,
+        logger: opts.logger,
+        fetchEmail: opts.fetchEmail,
+    });
+    const json = (await res.json());
+    return json.id;
+}
+/**
+ * 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 async function ensureFolderPath(opts) {
+    let parentId;
+    for (const name of opts.folderPath) {
+        const existing = await list({
+            appId: opts.appId,
+            projectId: opts.projectId,
+            clientId: opts.clientId,
+            interactive: opts.interactive,
+            logger: opts.logger,
+            fetchEmail: opts.fetchEmail,
+            folderId: parentId,
+            mimeType: FOLDER_MIME_TYPE,
+            nameEquals: name,
+        });
+        if (existing.length > 0) {
+            parentId = existing[0].id;
+            continue;
+        }
+        parentId = await createFolder({
+            appId: opts.appId,
+            projectId: opts.projectId,
+            clientId: opts.clientId,
+            interactive: opts.interactive,
+            logger: opts.logger,
+            fetchEmail: opts.fetchEmail,
+            name,
+            parentId,
+        });
+    }
+    if (!parentId) {
+        // folderPath was empty — nothing to resolve. This should not happen for
+        // a correctly-configured factory (folderPath is required and expected
+        // to be non-empty), but guard rather than returning `undefined` as a
+        // string.
+        throw new Error('ensureFolderPath: folderPath must contain at least one segment');
+    }
+    return parentId;
+}

package/dist/gis.d.ts

@@ -0,0 +1,8 @@
+import type { Logger } from './logger.js';
+/**
+ * Resolves once `window.google.accounts.oauth2.initTokenClient` becomes
+ * available, polling every 100ms. Rejects with a GisLoadError if it does not
+ * become available within 10 seconds. Uses real timers so this behaves
+ * correctly under `vi.useFakeTimers()`.
+ */
+export declare function waitForGoogleIdentityServices(logger?: Logger): Promise<void>;

package/dist/gis.js

@@ -0,0 +1,33 @@
+import { GisLoadError } from './errors.js';
+const POLL_INTERVAL_MS = 100;
+const TIMEOUT_MS = 10_000;
+function isGisAvailable() {
+    const w = globalThis;
+    return typeof w.google?.accounts?.oauth2?.initTokenClient !== 'undefined';
+}
+/**
+ * Resolves once `window.google.accounts.oauth2.initTokenClient` becomes
+ * available, polling every 100ms. Rejects with a GisLoadError if it does not
+ * become available within 10 seconds. Uses real timers so this behaves
+ * correctly under `vi.useFakeTimers()`.
+ */
+export function waitForGoogleIdentityServices(logger) {
+    if (isGisAvailable()) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        const startedAt = Date.now();
+        const interval = setInterval(() => {
+            logger?.debug('drive-sync: polling for Google Identity Services...');
+            if (isGisAvailable()) {
+                clearInterval(interval);
+                resolve();
+                return;
+            }
+            if (Date.now() - startedAt >= TIMEOUT_MS) {
+                clearInterval(interval);
+                reject(new GisLoadError());
+            }
+        }, POLL_INTERVAL_MS);
+    });
+}

package/dist/http.d.ts

@@ -0,0 +1,32 @@
+import type { Logger } from './logger.js';
+export interface DriveFetchOptions {
+    appId: string;
+    projectId: string;
+    clientId: string;
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: BodyInit;
+    interactive?: boolean;
+    requiredScopes: string[];
+    logger?: Logger;
+    /**
+     * Resolves the connected account's email from a fresh access token. When
+     * supplied (index.ts always wires the real implementation in), a 401's
+     * silent-refresh-and-retry goes through `refreshSilently` (connection.ts)
+     * instead of a bare `acquireToken`, so a token GIS silently hands back for
+     * the WRONG Google account is detected and surfaces as a typed
+     * `WrongAccountError` rather than being used transparently. Optional so
+     * this module has no hard dependency on a network implementation.
+     */
+    fetchEmail?: (accessToken: string) => Promise<string>;
+}
+/**
+ * Single entry point for all Drive API HTTP calls. Handles token
+ * acquisition/attachment, 429/5xx retry with backoff, 401 silent-refresh-and-
+ * retry-once, and 403/404 error normalization. Every response is checked for
+ * `.ok` before any body is parsed by this function or its callers — callers
+ * (files.ts, permissions.ts) receive the raw Response on success and must
+ * call .json()/.text()/.blob() themselves.
+ */
+export declare function driveFetch(opts: DriveFetchOptions): Promise<Response>;

package/dist/http.js

@@ -0,0 +1,188 @@
+import { acquireToken } from './token.js';
+import { getConnection, refreshSilently } from './connection.js';
+import { clearToken } from './storage.js';
+import { DriveSyncError, NeedsReauthError, ScopeInsufficientError, NotFoundError, RateLimitedError, TransientError, WrongAccountError, } from './errors.js';
+const MAX_ATTEMPTS = 3;
+const BASE_DELAY_MS = 500;
+function isRetryableStatus(status) {
+    return status === 429 || (status >= 500 && status <= 599);
+}
+/** Parses a `Retry-After` header (seconds, per HTTP spec) into milliseconds. */
+function retryAfterMs(res) {
+    const header = res.headers.get('Retry-After');
+    if (!header)
+        return undefined;
+    const seconds = Number(header);
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return undefined;
+    return seconds * 1000;
+}
+function retryAfterSeconds(res) {
+    const header = res.headers.get('Retry-After');
+    if (!header)
+        return undefined;
+    const seconds = Number(header);
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return undefined;
+    return seconds;
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Single entry point for all Drive API HTTP calls. Handles token
+ * acquisition/attachment, 429/5xx retry with backoff, 401 silent-refresh-and-
+ * retry-once, and 403/404 error normalization. Every response is checked for
+ * `.ok` before any body is parsed by this function or its callers — callers
+ * (files.ts, permissions.ts) receive the raw Response on success and must
+ * call .json()/.text()/.blob() themselves.
+ */
+export async function driveFetch(opts) {
+    const { appId, projectId, clientId, requiredScopes, logger } = opts;
+    const interactive = !!opts.interactive;
+    // Resolve a hint email from the current connection (if any) so a
+    // non-interactive silent refresh can target the right account. If there is
+    // no connection at all and interactive is false, acquireToken's silent
+    // request (hint: undefined) will fail on GIS's side and surface as
+    // NeedsReauthError from acquireToken itself — we deliberately let that
+    // propagate rather than pre-emptively short-circuiting here, since
+    // acquireToken/GIS is the single source of truth for "can we get a token".
+    const conn = await getConnection({ appId, projectId, requiredScopes });
+    const hint = conn?.email;
+    const token = await acquireToken({
+        appId,
+        projectId,
+        clientId,
+        scopes: requiredScopes,
+        interactive,
+        hint,
+        logger,
+    });
+    return performFetch(opts, token.accessToken, /* isRetryAfter401 */ false);
+}
+async function performFetch(opts, accessToken, isRetryAfter401) {
+    const { appId, projectId, clientId, url, method, body, requiredScopes, logger } = opts;
+    const interactive = !!opts.interactive;
+    const headers = {
+        ...opts.headers,
+        Authorization: `Bearer ${accessToken}`,
+    };
+    let res;
+    let lastBodyText = '';
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        res = await fetch(url, { method, headers, body });
+        if (res.ok) {
+            return res;
+        }
+        if (isRetryableStatus(res.status) && attempt < MAX_ATTEMPTS) {
+            const retryAfter = retryAfterMs(res);
+            const delayMs = retryAfter ?? BASE_DELAY_MS * 2 ** (attempt - 1);
+            logger?.warn('drive-sync: retrying Drive request', {
+                status: res.status,
+                attempt,
+                delayMs,
+            });
+            await sleep(delayMs);
+            continue;
+        }
+        // Either not retryable, or attempts exhausted — fall through to
+        // status-specific handling below using this final response.
+        break;
+    }
+    // res is guaranteed to be set (loop runs at least once).
+    const finalRes = res;
+    if (finalRes.ok) {
+        return finalRes;
+    }
+    lastBodyText = await finalRes.text();
+    if (isRetryableStatus(finalRes.status)) {
+        if (finalRes.status === 429) {
+            throw new RateLimitedError({
+                status: 429,
+                reason: lastBodyText,
+                retryAfter: retryAfterSeconds(finalRes),
+            });
+        }
+        throw new TransientError(`Drive request failed with status ${finalRes.status}: ${lastBodyText}`, { status: finalRes.status, reason: lastBodyText });
+    }
+    if (finalRes.status === 401) {
+        if (isRetryAfter401 || interactive) {
+            // Either this IS the retry attempt (already tried a silent refresh
+            // once and it still 401'd), or the original call was interactive
+            // (caller is expected to have already gone through a fresh
+            // connect()-style consent flow) — either way, do not attempt another
+            // refresh; surface as NeedsReauthError.
+            throw new NeedsReauthError('Drive request unauthorized (401)', {
+                status: 401,
+                reason: lastBodyText,
+            });
+        }
+        await clearToken(appId, projectId);
+        let refreshed;
+        try {
+            // Re-read the connection to find the email a verified silent refresh
+            // must land on. Purely a local storage read — no network call.
+            const conn = await getConnection({ appId, projectId, requiredScopes });
+            if (conn?.email && opts.fetchEmail) {
+                refreshed = await refreshSilently({
+                    appId,
+                    projectId,
+                    clientId,
+                    scopes: requiredScopes,
+                    expectedEmail: conn.email,
+                    fetchEmail: opts.fetchEmail,
+                    logger,
+                });
+            }
+            else {
+                refreshed = await acquireToken({
+                    appId,
+                    projectId,
+                    clientId,
+                    scopes: requiredScopes,
+                    interactive: false,
+                    hint: conn?.email,
+                    logger,
+                });
+            }
+        }
+        catch (err) {
+            if (err instanceof WrongAccountError) {
+                // Not a plain "can't get a token" failure — surface as-is so the
+                // caller knows a DIFFERENT account was silently authenticated,
+                // rather than masking it behind a generic reauth error. The bad
+                // token was already cleared by refreshSilently.
+                throw err;
+            }
+            throw new NeedsReauthError('Drive request unauthorized (401); silent refresh failed', {
+                status: 401,
+                reason: lastBodyText,
+            });
+        }
+        return performFetch(opts, refreshed.accessToken, /* isRetryAfter401 */ true);
+    }
+    if (finalRes.status === 403) {
+        if (lastBodyText.includes('ACCESS_TOKEN_SCOPE_INSUFFICIENT')) {
+            await clearToken(appId, projectId);
+            throw new ScopeInsufficientError('Access token has insufficient scope', {
+                status: 403,
+                reason: lastBodyText,
+            });
+        }
+        throw new DriveSyncError(`Drive request forbidden (403): ${lastBodyText}`, {
+            status: 403,
+            reason: lastBodyText,
+        });
+    }
+    if (finalRes.status === 404) {
+        // No fileId is reliably available at this layer (the URL may be a
+        // search/list/upload endpoint rather than a single-file get); callers
+        // that have a fileId in scope should catch this generic 404 and
+        // translate it into a NotFoundError with the fileId attached. We throw
+        // NotFoundError here with an empty fileId as a reasonable default so a
+        // raw un-typed error never surfaces, but files.ts/permissions.ts are
+        // expected to re-throw with the concrete fileId when they have one.
+        throw new NotFoundError('', { status: 404, reason: lastBodyText });
+    }
+    throw new DriveSyncError(`Drive request failed with status ${finalRes.status}: ${lastBodyText}`, { status: finalRes.status, reason: lastBodyText });
+}

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import type { CallOptions, Connection, DriveSyncOptions, DrivePermission, FileRef } from './types.js';
+export type { DriveSyncOptions, Connection, StoredToken, FileRef, DrivePermission, CallOptions } from './types.js';
+export * from './errors.js';
+export interface FilesHandle {
+    list(opts?: {
+        folderId?: string;
+        mimeType?: string;
+        nameEquals?: string;
+    }, callOpts?: CallOptions): Promise<FileRef[]>;
+    read(fileId: string, callOpts?: CallOptions): Promise<string | Blob | null>;
+    write(opts: {
+        fileId?: string;
+        folderId?: string;
+        name?: string;
+        content: string | Blob;
+        mimeType: string;
+    }, callOpts?: CallOptions): Promise<FileRef>;
+    remove(fileId: string, callOpts?: CallOptions): Promise<void>;
+}
+export interface PermissionsHandle {
+    list(fileId: string, callOpts?: CallOptions): Promise<DrivePermission[]>;
+    grant(opts: {
+        fileId: string;
+        type: 'user' | 'anyone';
+        role: string;
+        emailAddress?: string;
+    }, callOpts?: CallOptions): Promise<DrivePermission>;
+    update(opts: {
+        fileId: string;
+        permissionId: string;
+        role: string;
+    }, callOpts?: CallOptions): Promise<DrivePermission>;
+    revoke(opts: {
+        fileId: string;
+        permissionId: string;
+    }, callOpts?: CallOptions): Promise<void>;
+}
+export interface ProjectHandle {
+    connect(): Promise<Connection>;
+    getConnection(): Promise<Connection | null>;
+    disconnect(): Promise<void>;
+    ensureFolderPath(): Promise<string>;
+    files: FilesHandle;
+    permissions: PermissionsHandle;
+}
+export interface DriveSync {
+    activate(): () => void;
+    reconcile(knownProjectIds: string[]): Promise<void>;
+    dropProject(projectId: string): Promise<void>;
+    project(projectId: string): ProjectHandle;
+}
+/**
+ * Creates the drive-sync facade. `createDriveSync` itself attaches NO
+ * listeners and makes NO network calls — everything is deferred until the
+ * returned object's methods are actually called.
+ */
+export declare function createDriveSync(options: DriveSyncOptions): DriveSync;