@aloth/olcli 0.15.2 → 0.16.0

package/dist/client.js

@@ -18,15 +18,28 @@ import * as cheerio from 'cheerio';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import * as https from 'node:https';
-import * as http from 'node:http';
+import { routeRequest } from './proxy.js';
 import { RejectConflictError, buildUserDirectory, planRejection, renderRejectionDiff, describeAuthor, parseHistoryOtChanges, parseShareJsChanges } from './tracked-changes.js';
+import { planEntityMove } from './move-plan.js';
+import { matchProject } from './project-match.js';
+import { HttpStatusError, SessionExpiredError, httpError, isAuthStatus } from './errors.js';
 // Read version from package.json
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
 const USER_AGENT = `olcli/${pkg.version}`;
 const DEFAULT_BASE_URL = 'https://www.overleaf.com';
 const RESOURCE_PATH_FAILURE_HINT = ' (Perhaps the resource file you specified does not exist in the project?)';
+/**
+ * True when a redirect from `fromUrl` points at Overleaf's login page. A
+ * request to /login itself is the password flow and is never treated as one.
+ */
+export function isLoginRedirect(fromUrl, location) {
+    const from = new URL(fromUrl);
+    if (from.pathname === '/login')
+        return false;
+    const target = new URL(location, fromUrl);
+    return target.pathname === '/login' || target.pathname.endsWith('/login');
+}
 export const DEFAULT_COMMENT_CONCURRENCY = 4;
 export const MAX_COMMENT_CONCURRENCY = 8;
 /**
@@ -50,6 +63,8 @@ export class OverleafClient {
     csrf;
     baseUrl;
     verbose = false;
+    /** Email of the signed-in account, when the bootstrap page named it. */
+    accountEmail;
     timeoutMs = 10000;
     // Cache per-project folder trees so repeated uploads in sync/upload calls
     // don't re-fetch the tree via Socket.IO on every file.
@@ -162,21 +177,23 @@ export class OverleafClient {
             expect: 'text'
         });
         if (!response.ok) {
-            throw new Error(`Failed to fetch projects page: ${response.status}`);
+            throw httpError('Failed to fetch projects page', response.status);
         }
         bootstrapClient.applySetCookieHeaders(response.headers['set-cookie']);
         const html = response.body;
         const $ = cheerio.load(html);
         if (OverleafClient.isLoginPage($)) {
-            throw new Error('Authentication required. Session may have expired.');
+            throw new SessionExpiredError('Overleaf answered with its login page');
         }
         const csrf = OverleafClient.extractCsrfToken($);
         if (!csrf) {
-            throw new Error('Could not find CSRF token. Session may have expired.');
+            throw new SessionExpiredError('No CSRF token on the project page');
         }
         // Update cookies if the bootstrap request added anything
         const updatedCookies = bootstrapClient.cookies;
-        return new OverleafClient({ cookies: updatedCookies, csrf, baseUrl });
+        const client = new OverleafClient({ cookies: updatedCookies, csrf, baseUrl });
+        client.accountEmail = OverleafClient.extractAccountEmail($);
+        return client;
     }
     /**
      * Create client by submitting Overleaf's email/password login form.
@@ -188,7 +205,7 @@ export class OverleafClient {
             expect: 'text'
         });
         if (!loginPage.ok) {
-            throw new Error(`Failed to fetch login page: ${loginPage.status}`);
+            throw new HttpStatusError('Failed to fetch login page', loginPage.status);
         }
         bootstrapClient.applySetCookieHeaders(loginPage.headers['set-cookie']);
         const loginHtml = loginPage.body;
@@ -222,7 +239,7 @@ export class OverleafClient {
             if (loginFailure) {
                 throw new Error('Password login failed. Email or password may be incorrect.');
             }
-            throw new Error(`Password login failed: ${loginResponse.status}`);
+            throw new HttpStatusError('Password login failed', loginResponse.status);
         }
         const projectUrl = new URL(loginResponse.headers.location || '/project', baseUrl).toString();
         const projectPage = await bootstrapClient.httpRequest(projectUrl, {
@@ -233,7 +250,7 @@ export class OverleafClient {
             expect: 'text'
         });
         if (!projectPage.ok) {
-            throw new Error(`Failed to fetch projects page after login: ${projectPage.status}`);
+            throw httpError('Failed to fetch projects page after login', projectPage.status);
         }
         bootstrapClient.applySetCookieHeaders(projectPage.headers['set-cookie']);
         const projectHtml = projectPage.body;
@@ -245,7 +262,9 @@ export class OverleafClient {
         if (!projectCsrf) {
             throw new Error('Could not find CSRF token after password login.');
         }
-        return new OverleafClient({ cookies: bootstrapClient.cookies, csrf: projectCsrf, baseUrl });
+        const client = new OverleafClient({ cookies: bootstrapClient.cookies, csrf: projectCsrf, baseUrl });
+        client.accountEmail = OverleafClient.extractAccountEmail($project) ?? email;
+        return client;
     }
     /**
      * Pull the CSRF token out of a rendered Overleaf page.
@@ -281,6 +300,28 @@ export class OverleafClient {
         }
         return csrf;
     }
+    /**
+     * The signed-in account's email from a rendered Overleaf page, when the
+     * page carries one. `ol-usersEmail` is on the project dashboard; `ol-user`
+     * (JSON) is on the editor and on older releases. Display only.
+     */
+    static extractAccountEmail($) {
+        const direct = $('meta[name="ol-usersEmail"]').attr('content');
+        if (direct)
+            return direct;
+        const user = $('meta[name="ol-user"]').attr('content');
+        if (user) {
+            try {
+                const parsed = JSON.parse(user);
+                if (typeof parsed?.email === 'string' && parsed.email)
+                    return parsed.email;
+            }
+            catch {
+                // Not JSON on this release; no email to show.
+            }
+        }
+        return undefined;
+    }
     static isLoginPage($) {
         return $('form[name="loginForm"]').length > 0 || $('input[name="password"]').length > 0;
     }
@@ -348,12 +389,25 @@ export class OverleafClient {
         }
         const doRequest = (reqUrl, redirectsLeft) => {
             return new Promise((resolve, reject) => {
-                const parsedUrl = new URL(reqUrl);
-                const transport = parsedUrl.protocol === 'https:' ? https : http;
                 const headers = this.normalizeHeaders({ ...extraHeaders, ...options.headers });
-                const req = transport.request(reqUrl, { method, headers }, (res) => {
+                // HTTPS_PROXY / HTTP_PROXY / NO_PROXY: every request, the socket
+                // polling included, goes through here. See src/proxy.ts.
+                const route = routeRequest(reqUrl, headers);
+                if (route.proxy)
+                    this.logVerbose(`${method} ${reqUrl} via proxy ${route.proxy.host}`);
+                const req = route.transport.request(route.url, { ...route.options, method }, (res) => {
                     const status = res.statusCode || 0;
                     const resHeaders = res.headers;
+                    // Overleaf answers an expired session on any page with a redirect to
+                    // /login. Following it would hand an HTML login form to a caller
+                    // that expected JSON or a zip, and the user would see a parse error.
+                    if (status >= 300 && status < 400 && res.headers.location
+                        && isLoginRedirect(reqUrl, res.headers.location)) {
+                        this.logVerbose(`${method} ${reqUrl} -> ${status} redirect to login page`);
+                        res.resume();
+                        reject(new SessionExpiredError(`HTTP ${status} redirect to the login page from ${new URL(reqUrl).pathname}`, status));
+                        return;
+                    }
                     if (status >= 300 && status < 400 && res.headers.location && redirectsLeft > 0) {
                         this.logVerbose(`${method} ${reqUrl} -> ${status} redirect -> ${res.headers.location}`);
                         const redirectUrl = new URL(res.headers.location, reqUrl).toString();
@@ -415,7 +469,7 @@ export class OverleafClient {
             expect: 'text'
         });
         if (!response.ok) {
-            throw new Error(`Failed to fetch projects: ${response.status}`);
+            throw httpError('Failed to fetch projects', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
         const html = response.body;
@@ -488,6 +542,19 @@ export class OverleafClient {
         const projects = await this.listProjects();
         return projects.find(p => p.name === name);
     }
+    /**
+     * Find a project by ID or by what a user typed for its name: exact name,
+     * then case-insensitive, then a unique prefix. Throws ProjectNotFoundError
+     * (with "Did you mean" suggestions) or AmbiguousProjectError.
+     * `getProject` keeps its exact-match contract for library callers.
+     */
+    async findProject(query) {
+        const projects = await this.listProjects();
+        const byId = projects.find(p => p.id === query);
+        if (byId)
+            return byId;
+        return matchProject(projects, query);
+    }
     /**
      * Get project by ID
      */
@@ -517,7 +584,7 @@ export class OverleafClient {
             expect: 'json'
         });
         if (!response.ok) {
-            throw new Error(`Failed to create project: ${response.status}`);
+            throw httpError('Failed to create project', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
         const projectId = response.body?.project_id;
@@ -540,7 +607,7 @@ export class OverleafClient {
             expect: 'text'
         });
         if (!response.ok) {
-            throw new Error(`Failed to fetch project info: ${response.status}`);
+            throw httpError('Failed to fetch project info', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
         const html = response.body;
@@ -696,7 +763,7 @@ export class OverleafClient {
             timeoutMs
         });
         if (!response.ok) {
-            throw new Error(`Download failed: ${response.status}`);
+            throw httpError('Download failed', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
         return response.body;
@@ -721,7 +788,7 @@ export class OverleafClient {
             expect: 'json'
         });
         if (!response.ok) {
-            throw new Error(`Failed to compile project: ${response.status}`);
+            throw httpError('Failed to compile project', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
         const data = response.body;
@@ -769,7 +836,7 @@ export class OverleafClient {
             throw new Error('Folder already exists');
         }
         if (!response.ok) {
-            throw new Error(`Failed to create folder: ${response.status}`);
+            throw httpError('Failed to create folder', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
         const data = response.body;
@@ -893,9 +960,7 @@ export class OverleafClient {
             timeoutMs: 5000
         });
         if (!handshakeResponse.ok) {
-            const error = new Error(`Failed to open project socket: ${handshakeResponse.status}`);
-            error.status = handshakeResponse.status;
-            throw error;
+            throw httpError('Failed to open project socket', handshakeResponse.status);
         }
         this.applySetCookieHeaders(handshakeResponse.headers['set-cookie']);
         const sid = handshakeResponse.body.trim().split(':')[0];
@@ -931,7 +996,7 @@ export class OverleafClient {
             timeoutMs: 7000
         });
         if (!response.ok) {
-            throw new Error(`Socket poll failed: ${response.status}`);
+            throw httpError('Socket poll failed', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
         const packets = this.decodeSocketIoPayload(response.body);
@@ -966,7 +1031,7 @@ export class OverleafClient {
             timeoutMs: 5000
         });
         if (!response.ok) {
-            throw new Error(`Socket post failed: ${response.status}`);
+            throw httpError('Socket post failed', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
     }
@@ -1467,6 +1532,8 @@ export class OverleafClient {
                 expect: 'text'
             });
             if (!response.ok) {
+                if (isAuthStatus(response.status))
+                    throw httpError('Failed to upload file', response.status);
                 const text = response.body;
                 // Overleaf returns folder_not_found as HTTP 422 JSON.
                 // Parse the body first so caller can trigger folder probing fallback.
@@ -1530,7 +1597,7 @@ export class OverleafClient {
             expect: 'text'
         });
         if (!response.ok) {
-            throw new Error(`Failed to delete entity: ${response.status}`);
+            throw httpError('Failed to delete entity', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
     }
@@ -1543,7 +1610,7 @@ export class OverleafClient {
             expect: 'json'
         });
         if (!response.ok) {
-            throw new Error(`Failed to get entities: ${response.status}`);
+            throw httpError('Failed to get entities', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
         const data = response.body;
@@ -1597,7 +1664,7 @@ export class OverleafClient {
             expect: fileType === 'doc' ? 'json' : 'buffer'
         });
         if (!response.ok) {
-            throw new Error(`Failed to download file: ${response.status}`);
+            throw httpError('Failed to download file', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
         if (fileType === 'doc') {
@@ -1621,7 +1688,7 @@ export class OverleafClient {
             expect: 'text'
         });
         if (!response.ok) {
-            throw new Error(`Failed to rename entity: ${response.status}`);
+            throw httpError('Failed to rename entity', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
     }
@@ -1644,7 +1711,7 @@ export class OverleafClient {
             expect: 'text'
         });
         if (!response.ok) {
-            throw new Error(`Failed to rename project: ${response.status}`);
+            throw httpError('Failed to rename project', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
     }
@@ -1659,14 +1726,104 @@ export class OverleafClient {
         await this.deleteEntity(projectId, entity.id, entity.type);
     }
     /**
-     * Rename a file by path
+     * Move a file, doc, or folder into another folder, keeping its name.
+     * Overleaf answers 400 when the name is already taken in the target folder.
      */
-    async renameByPath(projectId, oldPath, newName) {
-        const entity = await this.findEntityByPath(projectId, oldPath);
-        if (!entity) {
-            throw new Error(`File not found: ${oldPath}`);
+    async moveEntity(projectId, entityId, entityType, folderId) {
+        const response = await this.httpRequest(`${this.baseUrl}/project/${projectId}/${entityType}/${entityId}/move`, {
+            method: 'POST',
+            headers: this.getHeaders(true),
+            body: JSON.stringify({ folder_id: folderId }),
+            expect: 'text'
+        });
+        if (!response.ok) {
+            const detail = typeof response.body === 'string' && response.body.trim() ? ` (${response.body.trim().slice(0, 200)})` : '';
+            throw httpError('Failed to move entity', response.status, detail.trim());
+        }
+        this.applySetCookieHeaders(response.headers['set-cookie']);
+    }
+    /**
+     * Work out what `rename|mv <source> <destination>` does, without writing.
+     * Throws MoveRefusedError when the request is refused. See move-plan.ts.
+     */
+    async planMove(projectId, source, destination) {
+        const projectInfo = await this.getProjectInfo(projectId);
+        const root = projectInfo.rootFolder?.[0];
+        if (!root?._id)
+            throw new Error('Could not read the project file tree');
+        return planEntityMove(root, source, destination);
+    }
+    /**
+     * Carry out a plan from planMove. Missing folders are created right before
+     * the move. If the second of two writes fails, the first one is undone so
+     * the entity keeps its old path; folders created on the way stay.
+     */
+    async applyMovePlan(projectId, plan) {
+        const { entity } = plan;
+        const createdFolders = [];
+        if (plan.noop)
+            return { from: plan.from, to: plan.to, createdFolders };
+        const ensureTargetFolder = async () => {
+            if (plan.targetFolderId)
+                return plan.targetFolderId;
+            const known = { ...plan.knownFolders };
+            for (const path of plan.createFolders) {
+                const parentPath = path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : '';
+                const name = path.slice(path.lastIndexOf('/') + 1);
+                known[path] = await this.createFolder(projectId, known[parentPath], name);
+                createdFolders.push(path);
+            }
+            return known[plan.targetFolderPath];
+        };
+        const doRename = () => this.renameEntity(projectId, entity.id, entity.type, plan.newName);
+        const doMove = async () => this.moveEntity(projectId, entity.id, entity.type, await ensureTargetFolder());
+        try {
+            if (!plan.move) {
+                await doRename();
+            }
+            else if (!plan.rename) {
+                await doMove();
+            }
+            else if (plan.order === 'rename-then-move') {
+                await doRename();
+                try {
+                    await doMove();
+                }
+                catch (error) {
+                    await this.renameEntity(projectId, entity.id, entity.type, entity.name).catch(() => undefined);
+                    throw error;
+                }
+            }
+            else {
+                await doMove();
+                try {
+                    await doRename();
+                }
+                catch (error) {
+                    await this.moveEntity(projectId, entity.id, entity.type, plan.sourceFolderId).catch(() => undefined);
+                    throw error;
+                }
+            }
+        }
+        finally {
+            this.invalidateFolderTree(projectId);
         }
-        await this.renameEntity(projectId, entity.id, entity.type, newName);
+        return { from: plan.from, to: plan.to, createdFolders };
+    }
+    /**
+     * Rename and/or move an entity by path. A destination without `/` renames
+     * in place; with a folder part it moves (creating missing folders); ending
+     * in `/` it moves and keeps the name; `/` alone is the project root.
+     */
+    async moveByPath(projectId, source, destination) {
+        const plan = await this.planMove(projectId, source, destination);
+        return this.applyMovePlan(projectId, plan);
+    }
+    /**
+     * Rename a file by path. `newName` may be a path, see moveByPath.
+     */
+    async renameByPath(projectId, oldPath, newName) {
+        await this.moveByPath(projectId, oldPath, newName);
     }
     /**
      * Download a file by path (uses zip as fallback if ID not available)
@@ -1707,7 +1864,7 @@ export class OverleafClient {
             expect: 'json'
         });
         if (!response.ok) {
-            throw new Error(`Failed to fetch comment threads: ${response.status}`);
+            throw httpError('Failed to fetch comment threads', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
         return response.body;
@@ -1941,7 +2098,7 @@ export class OverleafClient {
                 expect: 'text'
             });
             if (!response.ok) {
-                throw new Error(`Failed to accept tracked changes in ${changes[0].path}: ${response.status}`);
+                throw httpError(`Failed to accept tracked changes in ${changes[0].path}`, response.status);
             }
             this.applySetCookieHeaders(response.headers['set-cookie']);
         }
@@ -2088,7 +2245,7 @@ export class OverleafClient {
             expect: 'text'
         });
         if (!response.ok) {
-            throw new Error(`Failed to resolve comment: ${response.status}`);
+            throw httpError('Failed to resolve comment', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
         return comment;
@@ -2102,7 +2259,7 @@ export class OverleafClient {
             expect: 'text'
         });
         if (!response.ok) {
-            throw new Error(`Failed to reopen comment: ${response.status}`);
+            throw httpError('Failed to reopen comment', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
         return comment;
@@ -2116,7 +2273,7 @@ export class OverleafClient {
             expect: 'text'
         });
         if (!response.ok) {
-            throw new Error(`Failed to delete comment: ${response.status}`);
+            throw httpError('Failed to delete comment', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
         return comment;
@@ -2222,7 +2379,7 @@ export class OverleafClient {
             expect: 'text'
         });
         if (!response.ok) {
-            throw new Error(`Failed to post comment message: ${response.status}`);
+            throw httpError('Failed to post comment message', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
         if (!response.body)
@@ -2245,7 +2402,7 @@ export class OverleafClient {
             expect: 'json'
         });
         if (!response.ok) {
-            throw new Error(`Failed to compile project: ${response.status}`);
+            throw httpError('Failed to compile project', response.status);
         }
         this.applySetCookieHeaders(response.headers['set-cookie']);
         const data = response.body;