@open-webapp/drive-sync 0.1.0

package/dist/index.js

@@ -0,0 +1,207 @@
+import { noOpLogger } from './logger.js';
+import { connect as connectImpl, getConnection as getConnectionImpl, disconnect as disconnectImpl } from './connection.js';
+import { reconcile as reconcileImpl, dropProject as dropProjectImpl } from './reconcile.js';
+import * as filesImpl from './files.js';
+import * as permissionsImpl from './permissions.js';
+import { warmUpIfNeeded } from './refresh.js';
+import { REQUIRED_SCOPES } from './files.js';
+import { createBroadcast } from './broadcast.js';
+import { evictDbHandle } from './storage.js';
+import { notifyExternalTokenRefresh } from './token.js';
+export * from './errors.js';
+const USERINFO_URL = 'https://www.googleapis.com/oauth2/v3/userinfo';
+const REVOKE_URL = 'https://oauth2.googleapis.com/revoke';
+/**
+ * Resolves the connected account's email from a freshly-acquired access
+ * token. Implemented with a plain `fetch` (not `driveFetch`) because it is
+ * authenticated with a token obtained moments earlier in the SAME connect()
+ * call — there is no independent auth/retry concern here, so going through
+ * driveFetch's own internal token acquisition would be redundant and wrong
+ * (driveFetch always acquires its own token rather than accepting one).
+ */
+async function fetchEmail(accessToken) {
+    const res = await fetch(USERINFO_URL, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch userinfo: ${res.status}`);
+    }
+    const json = (await res.json());
+    if (!json.email) {
+        throw new Error('userinfo response did not include an email');
+    }
+    return json.email;
+}
+/** Fire-and-forget revoke against Google's real token revocation endpoint. */
+async function revokeToken(accessToken) {
+    await fetch(REVOKE_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: `token=${encodeURIComponent(accessToken)}`,
+    });
+}
+/**
+ * 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 function createDriveSync(options) {
+    const { appId, clientId, folderPath } = options;
+    const logger = options.logger ?? noOpLogger;
+    /**
+     * Design choice for `.activate()` (T30): the frozen public API's
+     * `activate()` takes no project argument, but the actual background
+     * token-refresh work (T29, refresh.ts) is inherently per-project. There is
+     * no explicit registry of "active projects" anywhere in the frozen API
+     * sketch, so this fills that gap by tracking, in this closure, every
+     * projectId that `.project(id)` has ever been called with. `.activate()`
+     * attaches exactly ONE global `visibilitychange`/`pageshow` listener pair
+     * (not one pair per project); when either fires, the handler iterates
+     * this live Set and runs refresh.ts's `warmUpIfNeeded` check for each
+     * tracked project. Because the Set is read at event-fire time (not
+     * snapshotted when `.activate()` is called), projects registered via
+     * `.project(id)` AFTER `.activate()` runs are still covered — call order
+     * between `.activate()` and `.project(id)` does not matter.
+     */
+    const trackedProjectIds = new Set();
+    function trackProject(projectId) {
+        trackedProjectIds.add(projectId);
+    }
+    /**
+     * Handles a cross-tab broadcast (see broadcast.ts) received while active.
+     * `logout`: another tab's disconnect() already cleared BOTH IndexedDB
+     * records (connection + token) before broadcasting, and this tab's own
+     * getConnection()/getToken() calls always read that same shared
+     * IndexedDB directly, so there is no stale in-memory Connection/email
+     * cache here to clear (index.ts, connection.ts, and refresh.ts hold no
+     * such cache). The one piece of genuinely in-memory, per-tab state is
+     * storage.ts's cached IDB *handle* — evicting it is a defensive no-op in
+     * practice (reads against an already-open handle already see the other
+     * tab's writes), but costs nothing and guards against any future
+     * handle-level caching assumptions.
+     * `token`: signals token.ts's per-tab in-flight-coalescing layer that a
+     * fresh token now sits in shared storage, so the NEXT non-interactive
+     * acquireToken() call for this project can skip its own GIS round-trip.
+     */
+    function handleBroadcast(msg) {
+        if (msg.type === 'logout') {
+            void evictDbHandle(appId, msg.projectId);
+        }
+        else if (msg.type === 'token') {
+            notifyExternalTokenRefresh(msg.projectId);
+        }
+    }
+    function activate() {
+        const disposeBroadcast = createBroadcast(appId).onMessage(handleBroadcast);
+        if (typeof document === 'undefined') {
+            return disposeBroadcast;
+        }
+        const runWarmUps = () => {
+            for (const projectId of trackedProjectIds) {
+                void warmUpIfNeeded({ appId, projectId, clientId, fetchEmail, logger });
+            }
+        };
+        const onVisibilityChange = () => {
+            if (document.visibilityState !== 'visible')
+                return;
+            runWarmUps();
+        };
+        const onPageShow = (event) => {
+            const persisted = event.persisted;
+            if (!persisted)
+                return;
+            if (document.hidden)
+                return;
+            runWarmUps();
+        };
+        document.addEventListener('visibilitychange', onVisibilityChange);
+        window.addEventListener('pageshow', onPageShow);
+        return () => {
+            disposeBroadcast();
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+            window.removeEventListener('pageshow', onPageShow);
+        };
+    }
+    function reconcile(knownProjectIds) {
+        return reconcileImpl(appId, knownProjectIds);
+    }
+    function dropProject(projectId) {
+        return dropProjectImpl(appId, projectId);
+    }
+    function project(projectId) {
+        trackProject(projectId);
+        const base = { appId, projectId, clientId, logger, fetchEmail };
+        const files = {
+            list(opts, callOpts) {
+                return filesImpl.list({ ...base, ...opts, interactive: callOpts?.interactive });
+            },
+            read(fileId, callOpts) {
+                return filesImpl.read({ ...base, fileId, interactive: callOpts?.interactive });
+            },
+            write(opts, callOpts) {
+                return filesImpl.write({ ...base, ...opts, interactive: callOpts?.interactive });
+            },
+            remove(fileId, callOpts) {
+                return filesImpl.remove({ ...base, fileId, interactive: callOpts?.interactive });
+            },
+        };
+        const permissions = {
+            list(fileId, callOpts) {
+                return permissionsImpl.list({ ...base, fileId, interactive: callOpts?.interactive });
+            },
+            grant(opts, callOpts) {
+                return permissionsImpl.grant({ ...base, ...opts, interactive: callOpts?.interactive });
+            },
+            update(opts, callOpts) {
+                return permissionsImpl.update({ ...base, ...opts, interactive: callOpts?.interactive });
+            },
+            revoke(opts, callOpts) {
+                return permissionsImpl.revoke({ ...base, ...opts, interactive: callOpts?.interactive });
+            },
+        };
+        return {
+            connect() {
+                return connectImpl({
+                    appId,
+                    projectId,
+                    clientId,
+                    scopes: REQUIRED_SCOPES,
+                    logger,
+                    fetchEmail,
+                });
+            },
+            getConnection() {
+                return getConnectionImpl({
+                    appId,
+                    projectId,
+                    requiredScopes: REQUIRED_SCOPES,
+                });
+            },
+            async disconnect() {
+                await disconnectImpl({
+                    appId,
+                    projectId,
+                    revokeFn: async (accessToken) => {
+                        try {
+                            await revokeToken(accessToken);
+                        }
+                        catch (err) {
+                            logger.warn('drive-sync: token revocation failed', { err });
+                        }
+                    },
+                });
+            },
+            ensureFolderPath() {
+                return filesImpl.ensureFolderPath({ ...base, folderPath });
+            },
+            files,
+            permissions,
+        };
+    }
+    return {
+        activate,
+        reconcile,
+        dropProject,
+        project,
+    };
+}

package/dist/logger.d.ts

@@ -0,0 +1,7 @@
+export interface Logger {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+export declare const noOpLogger: Logger;

package/dist/logger.js

@@ -0,0 +1,6 @@
+export const noOpLogger = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};

package/dist/permissions.d.ts

@@ -0,0 +1,37 @@
+import type { Logger } from './logger.js';
+import type { DrivePermission } from './types.js';
+interface BaseCallOptions {
+    appId: string;
+    projectId: string;
+    clientId: string;
+    interactive?: boolean;
+    logger?: Logger;
+    fetchEmail?: (accessToken: string) => Promise<string>;
+}
+export interface ListPermissionsOptions extends BaseCallOptions {
+    fileId: string;
+}
+export declare function list(opts: ListPermissionsOptions): Promise<DrivePermission[]>;
+export interface GrantPermissionOptions extends BaseCallOptions {
+    fileId: string;
+    type: 'user' | 'anyone';
+    role: string;
+    emailAddress?: string;
+}
+/**
+ * Folds the old separate "createAnyonePermission" helper into a single
+ * function keyed by `type`.
+ */
+export declare function grant(opts: GrantPermissionOptions): Promise<DrivePermission>;
+export interface UpdatePermissionOptions extends BaseCallOptions {
+    fileId: string;
+    permissionId: string;
+    role: string;
+}
+export declare function update(opts: UpdatePermissionOptions): Promise<DrivePermission>;
+export interface RevokePermissionOptions extends BaseCallOptions {
+    fileId: string;
+    permissionId: string;
+}
+export declare function revoke(opts: RevokePermissionOptions): Promise<void>;
+export {};

package/dist/permissions.js

@@ -0,0 +1,71 @@
+import { driveFetch } from './http.js';
+import { REQUIRED_SCOPES } from './files.js';
+const DRIVE_BASE = 'https://www.googleapis.com/drive/v3';
+export async function list(opts) {
+    const res = await driveFetch({
+        appId: opts.appId,
+        projectId: opts.projectId,
+        clientId: opts.clientId,
+        url: `${DRIVE_BASE}/files/${encodeURIComponent(opts.fileId)}/permissions?fields=${encodeURIComponent('permissions(id,type,role,emailAddress)')}`,
+        method: 'GET',
+        interactive: opts.interactive,
+        requiredScopes: REQUIRED_SCOPES,
+        logger: opts.logger,
+        fetchEmail: opts.fetchEmail,
+    });
+    const json = (await res.json());
+    return json.permissions ?? [];
+}
+/**
+ * Folds the old separate "createAnyonePermission" helper into a single
+ * function keyed by `type`.
+ */
+export async function grant(opts) {
+    const res = await driveFetch({
+        appId: opts.appId,
+        projectId: opts.projectId,
+        clientId: opts.clientId,
+        url: `${DRIVE_BASE}/files/${encodeURIComponent(opts.fileId)}/permissions`,
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            type: opts.type,
+            role: opts.role,
+            emailAddress: opts.type === 'user' ? opts.emailAddress : undefined,
+        }),
+        interactive: opts.interactive,
+        requiredScopes: REQUIRED_SCOPES,
+        logger: opts.logger,
+        fetchEmail: opts.fetchEmail,
+    });
+    return (await res.json());
+}
+export async function update(opts) {
+    const res = await driveFetch({
+        appId: opts.appId,
+        projectId: opts.projectId,
+        clientId: opts.clientId,
+        url: `${DRIVE_BASE}/files/${encodeURIComponent(opts.fileId)}/permissions/${encodeURIComponent(opts.permissionId)}`,
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ role: opts.role }),
+        interactive: opts.interactive,
+        requiredScopes: REQUIRED_SCOPES,
+        logger: opts.logger,
+        fetchEmail: opts.fetchEmail,
+    });
+    return (await res.json());
+}
+export async function revoke(opts) {
+    await driveFetch({
+        appId: opts.appId,
+        projectId: opts.projectId,
+        clientId: opts.clientId,
+        url: `${DRIVE_BASE}/files/${encodeURIComponent(opts.fileId)}/permissions/${encodeURIComponent(opts.permissionId)}`,
+        method: 'DELETE',
+        interactive: opts.interactive,
+        requiredScopes: REQUIRED_SCOPES,
+        logger: opts.logger,
+        fetchEmail: opts.fetchEmail,
+    });
+}

package/dist/query.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Escapes a literal string for safe embedding inside a Drive `q=` search
+ * parameter value, e.g. `name='...'`. Per Drive's query escaping rules,
+ * backslashes must be escaped FIRST, then single quotes — escaping the quote
+ * first would double-escape the backslashes just inserted for the quote.
+ */
+export declare function escapeQ(s: string): string;

package/dist/query.js

@@ -0,0 +1,9 @@
+/**
+ * Escapes a literal string for safe embedding inside a Drive `q=` search
+ * parameter value, e.g. `name='...'`. Per Drive's query escaping rules,
+ * backslashes must be escaped FIRST, then single quotes — escaping the quote
+ * first would double-escape the backslashes just inserted for the quote.
+ */
+export function escapeQ(s) {
+    return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}

package/dist/reconcile.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Safety-net cleanup: enumerate all owa-drive databases for this appId and
+ * delete any whose projectId is not in knownProjectIds. No-ops if
+ * indexedDB.databases() is unsupported (e.g. Firefox, older Safari).
+ */
+export declare function reconcile(appId: string, knownProjectIds: string[]): Promise<void>;
+/**
+ * Primary cleanup path: eagerly delete one specific project's database.
+ * Apps should call this directly when a project is removed rather than
+ * relying on reconcile() as the only mechanism.
+ */
+export declare function dropProject(appId: string, projectId: string): Promise<void>;

package/dist/reconcile.js

@@ -0,0 +1,45 @@
+import { evictDbHandle } from './storage.js';
+function dbPrefix(appId) {
+    return `owa-drive-${appId}-`;
+}
+function deleteDatabase(name) {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.deleteDatabase(name);
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error ?? new Error(`Failed to delete database ${name}`));
+        request.onblocked = () => resolve();
+    });
+}
+/**
+ * Safety-net cleanup: enumerate all owa-drive databases for this appId and
+ * delete any whose projectId is not in knownProjectIds. No-ops if
+ * indexedDB.databases() is unsupported (e.g. Firefox, older Safari).
+ */
+export async function reconcile(appId, knownProjectIds) {
+    if (typeof indexedDB === 'undefined' || typeof indexedDB.databases !== 'function') {
+        return;
+    }
+    const prefix = dbPrefix(appId);
+    const known = new Set(knownProjectIds);
+    const databases = await indexedDB.databases();
+    for (const { name } of databases) {
+        if (!name || !name.startsWith(prefix)) {
+            continue;
+        }
+        const projectId = name.slice(prefix.length);
+        if (!known.has(projectId)) {
+            await evictDbHandle(appId, projectId);
+            await deleteDatabase(name);
+        }
+    }
+}
+/**
+ * Primary cleanup path: eagerly delete one specific project's database.
+ * Apps should call this directly when a project is removed rather than
+ * relying on reconcile() as the only mechanism.
+ */
+export async function dropProject(appId, projectId) {
+    await evictDbHandle(appId, projectId);
+    const name = `${dbPrefix(appId)}${projectId}`;
+    await deleteDatabase(name);
+}

package/dist/refresh.d.ts

@@ -0,0 +1,34 @@
+import type { Logger } from './logger.js';
+export interface ActivateOptions {
+    appId: string;
+    projectId: string;
+    clientId: string;
+    /**
+     * Resolves the connected account's email from a fresh access token. When
+     * supplied, the warm-up's non-interactive refresh goes through
+     * `refreshSilently` (connection.ts) so a token GIS silently hands back for
+     * the wrong Google account is caught here in the background rather than
+     * only being discovered on the next foreground Drive call.
+     */
+    fetchEmail?: (accessToken: string) => Promise<string>;
+    logger?: Logger;
+}
+/**
+ * Per-project token warm-up check: if a connection exists AND its cached
+ * token is missing or within the refresh buffer of expiring, fires a
+ * non-interactive `acquireToken` warm-up in the background. Never starts a
+ * new attempt while the document is hidden (an already in-flight attempt
+ * from before the tab hid is allowed to run to completion — this function
+ * simply never being called with the tab hidden is enough to guarantee that,
+ * since it is only invoked from the visibility/pageshow handlers below,
+ * which already gate on visibility).
+ */
+export declare function warmUpIfNeeded(opts: ActivateOptions): Promise<void>;
+/**
+ * Attaches `visibilitychange` and `pageshow` (bfcache-restore) listeners for
+ * a single project, and returns a disposer that removes both. No listeners
+ * are attached at import time — only when this is called (from
+ * index.ts's top-level `activate()`, once per known project — see index.ts
+ * for how the project set is tracked).
+ */
+export declare function activate(opts: ActivateOptions): () => void;

package/dist/refresh.js

@@ -0,0 +1,89 @@
+import { getConnection, refreshSilently } from './connection.js';
+import { getToken } from './storage.js';
+import { acquireToken } from './token.js';
+import { REQUIRED_SCOPES } from './files.js';
+const REFRESH_BUFFER_MS = 5 * 60 * 1000;
+/**
+ * Per-project token warm-up check: if a connection exists AND its cached
+ * token is missing or within the refresh buffer of expiring, fires a
+ * non-interactive `acquireToken` warm-up in the background. Never starts a
+ * new attempt while the document is hidden (an already in-flight attempt
+ * from before the tab hid is allowed to run to completion — this function
+ * simply never being called with the tab hidden is enough to guarantee that,
+ * since it is only invoked from the visibility/pageshow handlers below,
+ * which already gate on visibility).
+ */
+export async function warmUpIfNeeded(opts) {
+    try {
+        const conn = await getConnection({
+            appId: opts.appId,
+            projectId: opts.projectId,
+            requiredScopes: REQUIRED_SCOPES,
+        });
+        if (!conn) {
+            // No connection at all -> no warm-up.
+            return;
+        }
+        const token = await getToken(opts.appId, opts.projectId);
+        const isStale = !token || token.expiresAt - Date.now() <= REFRESH_BUFFER_MS;
+        if (!isStale) {
+            return;
+        }
+        if (opts.fetchEmail) {
+            await refreshSilently({
+                appId: opts.appId,
+                projectId: opts.projectId,
+                clientId: opts.clientId,
+                scopes: REQUIRED_SCOPES,
+                expectedEmail: conn.email,
+                fetchEmail: opts.fetchEmail,
+                logger: opts.logger,
+            });
+        }
+        else {
+            await acquireToken({
+                appId: opts.appId,
+                projectId: opts.projectId,
+                clientId: opts.clientId,
+                scopes: REQUIRED_SCOPES,
+                interactive: false,
+                hint: conn.email,
+                logger: opts.logger,
+            });
+        }
+    }
+    catch (err) {
+        opts.logger?.warn('drive-sync: background token warm-up failed', { err });
+    }
+}
+/**
+ * Attaches `visibilitychange` and `pageshow` (bfcache-restore) listeners for
+ * a single project, and returns a disposer that removes both. No listeners
+ * are attached at import time — only when this is called (from
+ * index.ts's top-level `activate()`, once per known project — see index.ts
+ * for how the project set is tracked).
+ */
+export function activate(opts) {
+    if (typeof document === 'undefined') {
+        return () => { };
+    }
+    const onVisibilityChange = () => {
+        if (document.visibilityState !== 'visible')
+            return;
+        void warmUpIfNeeded(opts);
+    };
+    const onPageShow = (event) => {
+        const persisted = event.persisted;
+        if (!persisted)
+            return;
+        if (document.hidden)
+            return;
+        void warmUpIfNeeded(opts);
+    };
+    document.addEventListener('visibilitychange', onVisibilityChange);
+    window.addEventListener('pageshow', onPageShow);
+    return () => {
+        document.removeEventListener('visibilitychange', onVisibilityChange);
+        window.removeEventListener('pageshow', onPageShow);
+    };
+}

package/dist/storage.d.ts

@@ -0,0 +1,27 @@
+import { type IDBPDatabase, type DBSchema } from 'idb';
+import type { StoredToken } from './types.js';
+/** Durable connection record persisted under the 'conn' key of the auth store. */
+export interface ConnRecord {
+    email: string;
+    grantedScopes: string[];
+    connectedAt: number;
+}
+interface AuthDbSchema extends DBSchema {
+    auth: {
+        key: string;
+        value: ConnRecord | StoredToken;
+    };
+}
+export declare function openAuthDb(appId: string, projectId: string): Promise<IDBPDatabase<AuthDbSchema>>;
+/**
+ * Evict a cached DB handle from the in-memory cache (and close it if open).
+ * Does not delete the underlying IndexedDB database — see reconcile.ts for that.
+ */
+export declare function evictDbHandle(appId: string, projectId: string): Promise<void>;
+export declare function getConn(appId: string, projectId: string): Promise<ConnRecord | undefined>;
+export declare function setConn(appId: string, projectId: string, conn: ConnRecord): Promise<void>;
+export declare function clearConn(appId: string, projectId: string): Promise<void>;
+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 {};

package/dist/storage.js

@@ -0,0 +1,70 @@
+import { openDB } from 'idb';
+const AUTH_STORE = 'auth';
+const CONN_KEY = 'conn';
+const TOKEN_KEY = 'token';
+function dbName(appId, projectId) {
+    return `owa-drive-${appId}-${projectId}`;
+}
+function cacheKey(appId, projectId) {
+    return `${appId}:${projectId}`;
+}
+const dbCache = new Map();
+export function openAuthDb(appId, projectId) {
+    const key = cacheKey(appId, projectId);
+    let handle = dbCache.get(key);
+    if (!handle) {
+        handle = openDB(dbName(appId, projectId), 1, {
+            upgrade(db) {
+                if (!db.objectStoreNames.contains(AUTH_STORE)) {
+                    db.createObjectStore(AUTH_STORE);
+                }
+            },
+        });
+        dbCache.set(key, handle);
+    }
+    return handle;
+}
+/**
+ * Evict a cached DB handle from the in-memory cache (and close it if open).
+ * Does not delete the underlying IndexedDB database — see reconcile.ts for that.
+ */
+export async function evictDbHandle(appId, projectId) {
+    const key = cacheKey(appId, projectId);
+    const handle = dbCache.get(key);
+    dbCache.delete(key);
+    if (handle) {
+        try {
+            const db = await handle;
+            db.close();
+        }
+        catch {
+            // Ignore errors closing an already-broken handle.
+        }
+    }
+}
+export async function getConn(appId, projectId) {
+    const db = await openAuthDb(appId, projectId);
+    const value = await db.get(AUTH_STORE, CONN_KEY);
+    return value;
+}
+export async function setConn(appId, projectId, conn) {
+    const db = await openAuthDb(appId, projectId);
+    await db.put(AUTH_STORE, conn, CONN_KEY);
+}
+export async function clearConn(appId, projectId) {
+    const db = await openAuthDb(appId, projectId);
+    await db.delete(AUTH_STORE, CONN_KEY);
+}
+export async function getToken(appId, projectId) {
+    const db = await openAuthDb(appId, projectId);
+    const value = await db.get(AUTH_STORE, TOKEN_KEY);
+    return value;
+}
+export async function setToken(appId, projectId, token) {
+    const db = await openAuthDb(appId, projectId);
+    await db.put(AUTH_STORE, token, TOKEN_KEY);
+}
+export async function clearToken(appId, projectId) {
+    const db = await openAuthDb(appId, projectId);
+    await db.delete(AUTH_STORE, TOKEN_KEY);
+}