@aloth/olcli 0.1.6 → 0.1.8

package/dist/client.js

@@ -8,50 +8,62 @@ 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';
 // 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 BASE_URL = 'https://www.overleaf.com';
-const PROJECT_URL = `${BASE_URL}/project`;
-const DOWNLOAD_URL = `${BASE_URL}/project/{id}/download/zip`;
-const UPLOAD_URL = `${BASE_URL}/project/{id}/upload`;
-const FOLDER_URL = `${BASE_URL}/project/{id}/folder`;
-const DELETE_URL = `${BASE_URL}/project/{projectId}/{type}/{entityId}`;
-const COMPILE_URL = `${BASE_URL}/project/{id}/compile?enable_pdf_caching=true`;
+const DEFAULT_BASE_URL = 'https://www.overleaf.com';
 export class OverleafClient {
     cookies;
     csrf;
+    baseUrl;
     constructor(credentials) {
         this.cookies = credentials.cookies;
         this.csrf = credentials.csrf;
+        this.baseUrl = credentials.baseUrl || DEFAULT_BASE_URL;
+    }
+    projectUrl() {
+        return `${this.baseUrl}/project`;
+    }
+    downloadUrl(projectId) {
+        return `${this.baseUrl}/project/${projectId}/download/zip`;
+    }
+    uploadUrl(projectId) {
+        return `${this.baseUrl}/project/${projectId}/upload`;
+    }
+    folderUrl(projectId) {
+        return `${this.baseUrl}/project/${projectId}/folder`;
+    }
+    deleteUrl(projectId, entityType, entityId) {
+        return `${this.baseUrl}/project/${projectId}/${entityType}/${entityId}`;
+    }
+    compileUrl(projectId) {
+        return `${this.baseUrl}/project/${projectId}/compile?enable_pdf_caching=true`;
     }
     /**
      * Create client from session cookie string
      */
-    static async fromSessionCookie(sessionCookie) {
+    static async fromSessionCookie(sessionCookie, baseUrl = DEFAULT_BASE_URL, cookieName = 'overleaf_session2') {
         const cookies = {
-            'overleaf_session2': sessionCookie
+            [cookieName]: sessionCookie
         };
         // Fetch CSRF token from project page
-        const response = await fetch(PROJECT_URL, {
-            headers: {
-                'Cookie': Object.entries(cookies).map(([k, v]) => `${k}=${v}`).join('; '),
-                'User-Agent': USER_AGENT
-            }
+        const initialHeaders = {
+            'Cookie': Object.entries(cookies).map(([k, v]) => `${k}=${v}`).join('; '),
+            'User-Agent': USER_AGENT
+        };
+        const bootstrapClient = new OverleafClient({ cookies, csrf: 'bootstrap', baseUrl });
+        const response = await bootstrapClient.httpRequest(`${baseUrl}/project`, {
+            headers: initialHeaders,
+            expect: 'text'
         });
         if (!response.ok) {
-            throw new Error(`Failed to fetch projects page: ${response.status} ${response.statusText}`);
-        }
-        // Capture any new cookies from response
-        const setCookieHeaders = response.headers.getSetCookie?.() || [];
-        for (const setCookie of setCookieHeaders) {
-            const match = setCookie.match(/^([^=]+)=([^;]+)/);
-            if (match) {
-                cookies[match[1]] = match[2];
-            }
+            throw new Error(`Failed to fetch projects page: ${response.status}`);
         }
-        const html = await response.text();
+        bootstrapClient.applySetCookieHeaders(response.headers['set-cookie']);
+        const html = response.body;
         const $ = cheerio.load(html);
         // Try multiple methods to find CSRF token (based on PR #66, #82)
         let csrf;
@@ -76,30 +88,13 @@ export class OverleafClient {
         if (!csrf) {
             throw new Error('Could not find CSRF token. Session may have expired.');
         }
-        return new OverleafClient({ cookies, csrf });
+        // Update cookies if the bootstrap request added anything
+        const updatedCookies = bootstrapClient.cookies;
+        return new OverleafClient({ cookies: updatedCookies, csrf, baseUrl });
     }
     getCookieHeader() {
         return Object.entries(this.cookies).map(([k, v]) => `${k}=${v}`).join('; ');
     }
-    applySetCookieHeaders(headers) {
-        const setCookieHeaders = headers.getSetCookie?.() || [];
-        for (const setCookie of setCookieHeaders) {
-            const match = setCookie.match(/^([^=]+)=([^;]+)/);
-            if (match) {
-                this.cookies[match[1]] = match[2];
-            }
-        }
-    }
-    async fetchWithTimeout(url, init, timeoutMs) {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), timeoutMs);
-        try {
-            return await fetch(url, { ...init, signal: controller.signal });
-        }
-        finally {
-            clearTimeout(timeout);
-        }
-    }
     getHeaders(includeContentType = false) {
         const headers = {
             'Cookie': this.getCookieHeader(),
@@ -111,17 +106,93 @@ export class OverleafClient {
         }
         return headers;
     }
+    normalizeHeaders(headers) {
+        const normalized = {};
+        if (!headers)
+            return normalized;
+        for (const [key, value] of Object.entries(headers)) {
+            if (typeof value === 'string') {
+                normalized[key] = value;
+            }
+        }
+        return normalized;
+    }
+    applySetCookieHeaders(setCookie) {
+        if (!setCookie)
+            return;
+        for (const setCookieHeader of setCookie) {
+            const match = setCookieHeader.match(/^([^=]+)=([^;]+)/);
+            if (match) {
+                this.cookies[match[1]] = match[2];
+            }
+        }
+    }
+    async httpRequest(url, options = {}) {
+        const method = options.method || 'GET';
+        const timeoutMs = options.timeoutMs ?? 10000;
+        const maxRedirects = options.maxRedirects ?? 5;
+        const expect = options.expect ?? 'text';
+        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(options.headers);
+                const req = transport.request(reqUrl, { method, headers }, (res) => {
+                    const status = res.statusCode || 0;
+                    const resHeaders = res.headers;
+                    if (status >= 300 && status < 400 && res.headers.location && redirectsLeft > 0) {
+                        const redirectUrl = new URL(res.headers.location, reqUrl).toString();
+                        res.resume();
+                        doRequest(redirectUrl, redirectsLeft - 1).then(resolve, reject);
+                        return;
+                    }
+                    const chunks = [];
+                    res.on('data', (chunk) => chunks.push(chunk));
+                    res.on('end', () => {
+                        const buffer = Buffer.concat(chunks);
+                        let body = buffer;
+                        if (expect === 'text') {
+                            body = buffer.toString('utf-8');
+                        }
+                        else if (expect === 'json') {
+                            try {
+                                body = JSON.parse(buffer.toString('utf-8'));
+                            }
+                            catch (e) {
+                                return reject(new Error(`Failed to parse JSON response from ${reqUrl}`));
+                            }
+                        }
+                        resolve({ status, ok: status >= 200 && status < 300, headers: resHeaders, body });
+                    });
+                    res.on('error', reject);
+                });
+                req.on('error', reject);
+                if (timeoutMs) {
+                    req.setTimeout(timeoutMs, () => {
+                        req.destroy(new Error(`Request timeout after ${timeoutMs}ms`));
+                    });
+                }
+                if (options.body) {
+                    req.write(options.body);
+                }
+                req.end();
+            });
+        };
+        return doRequest(url, maxRedirects);
+    }
     /**
      * Get all projects (not archived, not trashed)
      */
     async listProjects() {
-        const response = await fetch(PROJECT_URL, {
-            headers: this.getHeaders()
+        const response = await this.httpRequest(this.projectUrl(), {
+            headers: this.getHeaders(),
+            expect: 'text'
         });
         if (!response.ok) {
             throw new Error(`Failed to fetch projects: ${response.status}`);
         }
-        const html = await response.text();
+        this.applySetCookieHeaders(response.headers['set-cookie']);
+        const html = response.body;
         const $ = cheerio.load(html);
         // Try new Overleaf structure first (PR #82)
         let projectsData = [];
@@ -198,13 +269,15 @@ export class OverleafClient {
      * Get detailed project info including file tree
      */
     async getProjectInfo(projectId) {
-        const response = await fetch(`${PROJECT_URL}/${projectId}`, {
-            headers: this.getHeaders()
+        const response = await this.httpRequest(`${this.projectUrl()}/${projectId}`, {
+            headers: this.getHeaders(),
+            expect: 'text'
         });
         if (!response.ok) {
             throw new Error(`Failed to fetch project info: ${response.status}`);
         }
-        const html = await response.text();
+        this.applySetCookieHeaders(response.headers['set-cookie']);
+        const html = response.body;
         const $ = cheerio.load(html);
         // Look for project data in meta tags
         let projectInfo;
@@ -247,34 +320,15 @@ export class OverleafClient {
      * project names). See: https://github.com/aloth/olcli/issues/2
      */
     async downloadBuffer(url) {
-        const { default: https } = await import('node:https');
-        const { default: http } = await import('node:http');
-        const doRequest = (reqUrl) => {
-            return new Promise((resolve, reject) => {
-                const parsedUrl = new URL(reqUrl);
-                const transport = parsedUrl.protocol === 'https:' ? https : http;
-                const req = transport.get(reqUrl, {
-                    headers: this.getHeaders(),
-                }, (res) => {
-                    // Follow redirects
-                    if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-                        const redirectUrl = new URL(res.headers.location, reqUrl).toString();
-                        doRequest(redirectUrl).then(resolve, reject);
-                        return;
-                    }
-                    if (res.statusCode && res.statusCode >= 400) {
-                        reject(new Error(`Download failed: ${res.statusCode}`));
-                        return;
-                    }
-                    const chunks = [];
-                    res.on('data', (chunk) => chunks.push(chunk));
-                    res.on('end', () => resolve(Buffer.concat(chunks)));
-                    res.on('error', reject);
-                });
-                req.on('error', reject);
-            });
-        };
-        return doRequest(url);
+        const response = await this.httpRequest(url, {
+            headers: this.getHeaders(),
+            expect: 'buffer'
+        });
+        if (!response.ok) {
+            throw new Error(`Download failed: ${response.status}`);
+        }
+        this.applySetCookieHeaders(response.headers['set-cookie']);
+        return response.body;
     }
     /**
      * Download project as zip
@@ -283,14 +337,13 @@ export class OverleafClient {
      * Content-Disposition headers. See: https://github.com/aloth/olcli/issues/2
      */
     async downloadProject(projectId) {
-        const url = DOWNLOAD_URL.replace('{id}', projectId);
-        return this.downloadBuffer(url);
+        return this.downloadBuffer(this.downloadUrl(projectId));
     }
     /**
      * Compile project and get PDF
      */
     async compileProject(projectId) {
-        const response = await fetch(COMPILE_URL.replace('{id}', projectId), {
+        const response = await this.httpRequest(this.compileUrl(projectId), {
             method: 'POST',
             headers: this.getHeaders(true),
             body: JSON.stringify({
@@ -298,12 +351,14 @@ export class OverleafClient {
                 draft: false,
                 check: 'silent',
                 incrementalCompilesEnabled: true
-            })
+            }),
+            expect: 'json'
         });
         if (!response.ok) {
             throw new Error(`Failed to compile project: ${response.status}`);
         }
-        const data = await response.json();
+        this.applySetCookieHeaders(response.headers['set-cookie']);
+        const data = response.body;
         if (data.status !== 'success') {
             throw new Error(`Compilation failed: ${data.status}`);
         }
@@ -312,7 +367,7 @@ export class OverleafClient {
             throw new Error('No PDF output found');
         }
         return {
-            pdfUrl: `${BASE_URL}${pdfFile.url}`,
+            pdfUrl: `${this.baseUrl}${pdfFile.url}`,
             logs: data.compileGroup ? [`Compile group: ${data.compileGroup}`] : []
         };
     }
@@ -327,13 +382,14 @@ export class OverleafClient {
      * Create a folder in a project
      */
     async createFolder(projectId, parentFolderId, name) {
-        const response = await fetch(FOLDER_URL.replace('{id}', projectId), {
+        const response = await this.httpRequest(this.folderUrl(projectId), {
             method: 'POST',
             headers: this.getHeaders(true),
             body: JSON.stringify({
                 parent_folder_id: parentFolderId,
                 name
-            })
+            }),
+            expect: 'json'
         });
         if (response.status === 400) {
             // Folder already exists
@@ -342,7 +398,8 @@ export class OverleafClient {
         if (!response.ok) {
             throw new Error(`Failed to create folder: ${response.status}`);
         }
-        const data = await response.json();
+        this.applySetCookieHeaders(response.headers['set-cookie']);
+        const data = response.body;
         return data._id;
     }
     /**
@@ -404,6 +461,35 @@ export class OverleafClient {
             return null;
         }
     }
+    /**
+     * Extract full folder tree from a Socket.IO joinProjectResponse packet.
+     * Returns a map of folder path -> folder ID, e.g. { '': rootId, 'figures': figuresId }
+     */
+    extractFolderTreeFromSocketPacket(packet) {
+        if (!packet.startsWith('5:::'))
+            return null;
+        try {
+            const payload = JSON.parse(packet.slice(4));
+            if (payload?.name !== 'joinProjectResponse')
+                return null;
+            const rootFolder = payload?.args?.[0]?.project?.rootFolder?.[0];
+            if (!rootFolder?._id)
+                return null;
+            const folderMap = {};
+            function walkFolders(folder, currentPath) {
+                folderMap[currentPath] = folder._id;
+                for (const sub of folder.folders || []) {
+                    const subPath = currentPath ? `${currentPath}/${sub.name}` : sub.name;
+                    walkFolders(sub, subPath);
+                }
+            }
+            walkFolders(rootFolder, '');
+            return folderMap;
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * main problem to resolve root folder ID from Overleaf's collaboration join payload
      * authoritative for projects where ObjectID arithmetic does not apply
@@ -411,34 +497,38 @@ export class OverleafClient {
     async getRootFolderIdFromSocket(projectId) {
         let sid = null;
         try {
-            const handshakeUrl = `${BASE_URL}/socket.io/1/?projectId=${encodeURIComponent(projectId)}&t=${Date.now()}`;
-            const handshakeResponse = await this.fetchWithTimeout(handshakeUrl, {
+            const handshakeUrl = `${this.baseUrl}/socket.io/1/?projectId=${encodeURIComponent(projectId)}&t=${Date.now()}`;
+            const handshakeResponse = await this.httpRequest(handshakeUrl, {
                 headers: {
                     'Cookie': this.getCookieHeader(),
                     'User-Agent': USER_AGENT
-                }
-            }, 5000);
+                },
+                expect: 'text',
+                timeoutMs: 5000
+            });
             if (!handshakeResponse.ok)
                 return null;
-            this.applySetCookieHeaders(handshakeResponse.headers);
-            const handshakeBody = (await handshakeResponse.text()).trim();
+            this.applySetCookieHeaders(handshakeResponse.headers['set-cookie']);
+            const handshakeBody = handshakeResponse.body.trim();
             sid = handshakeBody.split(':')[0];
             if (!sid)
                 return null;
-            const buildPollUrl = () => `${BASE_URL}/socket.io/1/xhr-polling/${sid}?projectId=${encodeURIComponent(projectId)}&t=${Date.now()}`;
+            const buildPollUrl = () => `${this.baseUrl}/socket.io/1/xhr-polling/${sid}?projectId=${encodeURIComponent(projectId)}&t=${Date.now()}`;
             let discoveredRootFolderId = null;
             // poll a few frames, first is usually connect ack, next includes joinProjectResponse
             for (let attempt = 0; attempt < 3; attempt++) {
-                const pollResponse = await this.fetchWithTimeout(buildPollUrl(), {
+                const pollResponse = await this.httpRequest(buildPollUrl(), {
                     headers: {
                         'Cookie': this.getCookieHeader(),
                         'User-Agent': USER_AGENT
-                    }
-                }, 5000);
+                    },
+                    expect: 'text',
+                    timeoutMs: 5000
+                });
                 if (!pollResponse.ok)
                     return null;
-                this.applySetCookieHeaders(pollResponse.headers);
-                const payload = await pollResponse.text();
+                this.applySetCookieHeaders(pollResponse.headers['set-cookie']);
+                const payload = pollResponse.body;
                 const packets = this.decodeSocketIoPayload(payload);
                 for (const packet of packets) {
                     const rootFolderId = this.extractRootFolderIdFromSocketPacket(packet);
@@ -448,16 +538,18 @@ export class OverleafClient {
                     }
                     if (packet.startsWith('2::')) {
                         //reply to heartbeat to keep polling transport alive
-                        const heartbeatResponse = await this.fetchWithTimeout(buildPollUrl(), {
+                        const heartbeatResponse = await this.httpRequest(buildPollUrl(), {
                             method: 'POST',
                             headers: {
                                 'Cookie': this.getCookieHeader(),
                                 'User-Agent': USER_AGENT,
                                 'Content-Type': 'text/plain;charset=UTF-8'
                             },
-                            body: '2::'
-                        }, 5000);
-                        this.applySetCookieHeaders(heartbeatResponse.headers);
+                            body: '2::',
+                            expect: 'text',
+                            timeoutMs: 5000
+                        });
+                        this.applySetCookieHeaders(heartbeatResponse.headers['set-cookie']);
                     }
                 }
                 if (discoveredRootFolderId) {
@@ -471,17 +563,19 @@ export class OverleafClient {
         finally {
             if (sid) {
                 try {
-                    const disconnectUrl = `${BASE_URL}/socket.io/1/xhr-polling/${sid}?projectId=${encodeURIComponent(projectId)}&t=${Date.now()}`;
-                    const disconnectResponse = await this.fetchWithTimeout(disconnectUrl, {
+                    const disconnectUrl = `${this.baseUrl}/socket.io/1/xhr-polling/${sid}?projectId=${encodeURIComponent(projectId)}&t=${Date.now()}`;
+                    const disconnectResponse = await this.httpRequest(disconnectUrl, {
                         method: 'POST',
                         headers: {
                             'Cookie': this.getCookieHeader(),
                             'User-Agent': USER_AGENT,
                             'Content-Type': 'text/plain;charset=UTF-8'
                         },
-                        body: '0::'
-                    }, 5000);
-                    this.applySetCookieHeaders(disconnectResponse.headers);
+                        body: '0::',
+                        expect: 'text',
+                        timeoutMs: 5000
+                    });
+                    this.applySetCookieHeaders(disconnectResponse.headers['set-cookie']);
                 }
                 catch {
                     // Ignore cleanup failures.
@@ -490,6 +584,134 @@ export class OverleafClient {
         }
         return null;
     }
+    /**
+     * Get full folder tree for a project via Socket.IO.
+     * Returns a map of folder path -> folder ID, e.g. { '': rootId, 'figures': figuresId }
+     */
+    async getFolderTreeFromSocket(projectId) {
+        let sid = null;
+        try {
+            const handshakeUrl = `${this.baseUrl}/socket.io/1/?projectId=${encodeURIComponent(projectId)}&t=${Date.now()}`;
+            const handshakeResponse = await this.httpRequest(handshakeUrl, {
+                headers: {
+                    'Cookie': this.getCookieHeader(),
+                    'User-Agent': USER_AGENT
+                },
+                expect: 'text',
+                timeoutMs: 5000
+            });
+            if (!handshakeResponse.ok)
+                return null;
+            this.applySetCookieHeaders(handshakeResponse.headers['set-cookie']);
+            const handshakeBody = handshakeResponse.body.trim();
+            sid = handshakeBody.split(':')[0];
+            if (!sid)
+                return null;
+            const buildPollUrl = () => `${this.baseUrl}/socket.io/1/xhr-polling/${sid}?projectId=${encodeURIComponent(projectId)}&t=${Date.now()}`;
+            for (let attempt = 0; attempt < 3; attempt++) {
+                const pollResponse = await this.httpRequest(buildPollUrl(), {
+                    headers: {
+                        'Cookie': this.getCookieHeader(),
+                        'User-Agent': USER_AGENT
+                    },
+                    expect: 'text',
+                    timeoutMs: 5000
+                });
+                if (!pollResponse.ok)
+                    return null;
+                this.applySetCookieHeaders(pollResponse.headers['set-cookie']);
+                const payload = pollResponse.body;
+                const packets = this.decodeSocketIoPayload(payload);
+                for (const packet of packets) {
+                    const folderTree = this.extractFolderTreeFromSocketPacket(packet);
+                    if (folderTree)
+                        return folderTree;
+                    if (packet.startsWith('2::')) {
+                        const heartbeatResponse = await this.httpRequest(buildPollUrl(), {
+                            method: 'POST',
+                            headers: {
+                                'Cookie': this.getCookieHeader(),
+                                'User-Agent': USER_AGENT,
+                                'Content-Type': 'text/plain;charset=UTF-8'
+                            },
+                            body: '2::',
+                            expect: 'text',
+                            timeoutMs: 5000
+                        });
+                        this.applySetCookieHeaders(heartbeatResponse.headers['set-cookie']);
+                    }
+                }
+            }
+        }
+        catch {
+            // Fall back
+        }
+        finally {
+            if (sid) {
+                try {
+                    const disconnectUrl = `${this.baseUrl}/socket.io/1/xhr-polling/${sid}?projectId=${encodeURIComponent(projectId)}&t=${Date.now()}`;
+                    await this.httpRequest(disconnectUrl, {
+                        method: 'POST',
+                        headers: {
+                            'Cookie': this.getCookieHeader(),
+                            'User-Agent': USER_AGENT,
+                            'Content-Type': 'text/plain;charset=UTF-8'
+                        },
+                        body: '0::',
+                        expect: 'text',
+                        timeoutMs: 5000
+                    });
+                }
+                catch {
+                    // Ignore cleanup failures.
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Resolve a folder path to a folder ID, creating missing folders as needed.
+     * folderTree is a map of path -> ID (fetched once per push session).
+     * folderPath is e.g. 'figures' or 'a/b/c'.
+     */
+    async resolveFolderId(projectId, folderTree, folderPath) {
+        if (!folderPath || folderPath === '')
+            return folderTree[''];
+        if (folderTree[folderPath])
+            return folderTree[folderPath];
+        // Create each missing segment
+        const segments = folderPath.split('/');
+        let currentPath = '';
+        for (const segment of segments) {
+            const parentPath = currentPath;
+            currentPath = currentPath ? `${currentPath}/${segment}` : segment;
+            if (folderTree[currentPath])
+                continue;
+            const parentId = folderTree[parentPath];
+            if (!parentId)
+                throw new Error(`Cannot resolve parent folder for: ${currentPath}`);
+            try {
+                const newId = await this.createFolder(projectId, parentId, segment);
+                folderTree[currentPath] = newId;
+            }
+            catch (e) {
+                if (e.message === 'Folder already exists') {
+                    // Folder exists but we don't have its ID - re-fetch tree
+                    const freshTree = await this.getFolderTreeFromSocket(projectId);
+                    if (freshTree?.[currentPath]) {
+                        folderTree[currentPath] = freshTree[currentPath];
+                    }
+                    else {
+                        throw new Error(`Folder '${currentPath}' exists but could not resolve its ID`);
+                    }
+                }
+                else {
+                    throw e;
+                }
+            }
+        }
+        return folderTree[folderPath];
+    }
     /**
      * Get root folder ID for a project (tries multiple methods)
      */
@@ -542,16 +764,21 @@ export class OverleafClient {
                 formData.append('name', testFileName);
                 formData.append('type', 'text/plain');
                 formData.append('qqfile', new Blob(['probe']), testFileName);
-                const response = await fetch(`${UPLOAD_URL.replace('{id}', projectId)}?folder_id=${folderId}`, {
+                const response = await this.httpRequest(`${this.uploadUrl(projectId)}?folder_id=${folderId}`, {
                     method: 'POST',
                     headers: {
                         'Cookie': this.getCookieHeader(),
                         'User-Agent': USER_AGENT,
                         'X-Csrf-Token': this.csrf
                     },
-                    body: formData
+                    body: formData,
+                    expect: 'json'
                 });
-                const data = await response.json();
+                if (!response.ok) {
+                    continue;
+                }
+                this.applySetCookieHeaders(response.headers['set-cookie']);
+                const data = response.body;
                 if (data.success !== false && data.entity_id) {
                     // Success! Delete the probe file and return this folder ID
                     try {
@@ -570,13 +797,22 @@ export class OverleafClient {
         return null;
     }
     /**
-     * Upload a file to a project
+     * Upload a file to a project.
+     * If folderTree is provided and fileName contains a path (e.g. 'figures/img.png'),
+     * the file will be uploaded into the correct subfolder, creating it if needed.
      */
-    async uploadFile(projectId, folderId, fileName, content) {
-        // If no folder ID provided, get the root folder
-        let targetFolderId = folderId || await this.getRootFolderId(projectId);
-        // Extract just the filename without path (PR #73 fix)
+    async uploadFile(projectId, folderId, fileName, content, folderTree) {
+        // Extract just the filename without path
         const baseName = fileName.split('/').pop() || fileName;
+        // Resolve target folder: if fileName has a directory part and we have a folderTree, use it
+        const dirPart = fileName.includes('/') ? fileName.split('/').slice(0, -1).join('/') : '';
+        let targetFolderId;
+        if (dirPart && folderTree) {
+            targetFolderId = await this.resolveFolderId(projectId, folderTree, dirPart);
+        }
+        else {
+            targetFolderId = folderId || await this.getRootFolderId(projectId);
+        }
         // Determine MIME type
         const ext = baseName.split('.').pop()?.toLowerCase() || '';
         const mimeTypes = {
@@ -600,17 +836,18 @@ export class OverleafClient {
             formData.append('name', baseName);
             formData.append('type', mimeType);
             formData.append('qqfile', new Blob([content]), baseName);
-            const response = await fetch(`${UPLOAD_URL.replace('{id}', projectId)}?folder_id=${encodeURIComponent(fid)}`, {
+            const response = await this.httpRequest(`${this.uploadUrl(projectId)}?folder_id=${encodeURIComponent(fid)}`, {
                 method: 'POST',
                 headers: {
                     'Cookie': this.getCookieHeader(),
                     'User-Agent': USER_AGENT,
                     'X-Csrf-Token': this.csrf
                 },
-                body: formData
+                body: formData,
+                expect: 'text'
             });
             if (!response.ok) {
-                const text = await response.text();
+                const text = response.body;
                 // Overleaf returns folder_not_found as HTTP 422 JSON.
                 // Parse the body first so caller can trigger folder probing fallback.
                 try {
@@ -624,7 +861,8 @@ export class OverleafClient {
                 }
                 return { success: false, error: `${response.status} - ${text}` };
             }
-            const data = await response.json();
+            this.applySetCookieHeaders(response.headers['set-cookie']);
+            const data = JSON.parse(response.body);
             if (data.success === false && data.error === 'folder_not_found') {
                 return { success: false, error: 'folder_not_found' };
             }
@@ -665,29 +903,30 @@ export class OverleafClient {
      * Delete a file or folder
      */
     async deleteEntity(projectId, entityId, entityType) {
-        const url = DELETE_URL
-            .replace('{projectId}', projectId)
-            .replace('{type}', entityType)
-            .replace('{entityId}', entityId);
-        const response = await fetch(url, {
+        const url = this.deleteUrl(projectId, entityType, entityId);
+        const response = await this.httpRequest(url, {
             method: 'DELETE',
-            headers: this.getHeaders()
+            headers: this.getHeaders(),
+            expect: 'text'
         });
         if (!response.ok) {
             throw new Error(`Failed to delete entity: ${response.status}`);
         }
+        this.applySetCookieHeaders(response.headers['set-cookie']);
     }
     /**
      * Get list of entities (files/docs) with paths
      */
     async getEntities(projectId) {
-        const response = await fetch(`${BASE_URL}/project/${projectId}/entities`, {
-            headers: this.getHeaders()
+        const response = await this.httpRequest(`${this.baseUrl}/project/${projectId}/entities`, {
+            headers: this.getHeaders(),
+            expect: 'json'
         });
         if (!response.ok) {
             throw new Error(`Failed to get entities: ${response.status}`);
         }
-        const data = await response.json();
+        this.applySetCookieHeaders(response.headers['set-cookie']);
+        const data = response.body;
         return data.entities || [];
     }
     /**
@@ -733,35 +972,38 @@ export class OverleafClient {
      */
     async downloadFile(projectId, fileId, fileType) {
         const endpoint = fileType === 'doc' ? 'doc' : 'file';
-        const response = await fetch(`${BASE_URL}/project/${projectId}/${endpoint}/${fileId}`, {
-            headers: this.getHeaders()
+        const response = await this.httpRequest(`${this.baseUrl}/project/${projectId}/${endpoint}/${fileId}`, {
+            headers: this.getHeaders(),
+            expect: fileType === 'doc' ? 'json' : 'buffer'
         });
         if (!response.ok) {
             throw new Error(`Failed to download file: ${response.status}`);
         }
+        this.applySetCookieHeaders(response.headers['set-cookie']);
         if (fileType === 'doc') {
             // Docs return JSON with lines array
-            const data = await response.json();
+            const data = response.body;
             const content = (data.lines || []).join('\n');
             return Buffer.from(content, 'utf-8');
         }
         else {
-            const arrayBuffer = await response.arrayBuffer();
-            return Buffer.from(arrayBuffer);
+            return response.body;
         }
     }
     /**
      * Rename a file, doc, or folder
      */
     async renameEntity(projectId, entityId, entityType, newName) {
-        const response = await fetch(`${BASE_URL}/project/${projectId}/${entityType}/${entityId}/rename`, {
+        const response = await this.httpRequest(`${this.baseUrl}/project/${projectId}/${entityType}/${entityId}/rename`, {
             method: 'POST',
             headers: this.getHeaders(true),
-            body: JSON.stringify({ name: newName })
+            body: JSON.stringify({ name: newName }),
+            expect: 'text'
         });
         if (!response.ok) {
             throw new Error(`Failed to rename entity: ${response.status}`);
         }
+        this.applySetCookieHeaders(response.headers['set-cookie']);
     }
     /**
      * Delete a file by path
@@ -820,7 +1062,7 @@ export class OverleafClient {
      * Compile project and get all output files
      */
     async compileWithOutputs(projectId) {
-        const response = await fetch(COMPILE_URL.replace('{id}', projectId), {
+        const response = await this.httpRequest(this.compileUrl(projectId), {
             method: 'POST',
             headers: this.getHeaders(true),
             body: JSON.stringify({
@@ -828,20 +1070,22 @@ export class OverleafClient {
                 draft: false,
                 check: 'silent',
                 incrementalCompilesEnabled: true
-            })
+            }),
+            expect: 'json'
         });
         if (!response.ok) {
             throw new Error(`Failed to compile project: ${response.status}`);
         }
-        const data = await response.json();
+        this.applySetCookieHeaders(response.headers['set-cookie']);
+        const data = response.body;
         const pdfFile = data.outputFiles?.find((f) => f.type === 'pdf');
         return {
             status: data.status,
-            pdfUrl: pdfFile ? `${BASE_URL}${pdfFile.url}` : undefined,
+            pdfUrl: pdfFile ? `${this.baseUrl}${pdfFile.url}` : undefined,
             outputFiles: (data.outputFiles || []).map((f) => ({
                 path: f.path,
                 type: f.type,
-                url: `${BASE_URL}${f.url}`
+                url: `${this.baseUrl}${f.url}`
             }))
         };
     }