@netique/overleaf-mcp 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# overleaf-mcp
+
+An MCP server for [Overleaf](https://www.overleaf.com) that lets a Claude or other agent navigate projects, read/edit `.tex` files, compile, and work with review-panel comments — over Overleaf's **real web/Socket.IO API**, the same channel the official web editor uses.
+
+The one feature no existing Overleaf MCP can deliver: when a project has **track-changes** enabled, the agent's edits appear as **pending suggestions in the Review panel**, the same way a human collaborator's edits do. You and your collaborators can accept or reject each suggestion. You can also ask the agend to accept/reject them (e.g. *"accept all suggestions about typos"*).
+
+## Why a new MCP
+
+The three existing Overleaf MCPs ([mjyoo2/overleafmcp](https://github.com/mjyoo2/overleafmcp), [YounesBensafia/overleaf-mcp-server](https://github.com/YounesBensafia/overleaf-mcp-server), [GhoshSrinjoy/Overleaf-mcp](https://github.com/GhoshSrinjoy/Overleaf-mcp)) all write through Overleaf's **Git bridge**, which has two problems for collaborative academic work:
+
+1. Commits show up in Overleaf with delay (the bridge polls).
+2. Git-bridge writes **bypass tracked changes entirely** — even when track-changes mode is on, edits land as direct overwrites, not as suggestions for review.
+
+The [`overleaf-workshop`](https://github.com/overleaf-workshop/overleaf-workshop) VSCode extension already uses Overleaf's Socket.IO API rather than Git, but doesn't yet emit tracked changes ([issue #94](https://github.com/overleaf-workshop/overleaf-workshop/issues/94)).
+
+`overleaf-mcp` solves both: a minimal Socket.IO 0.9 client over `fetch` + `ws@8`, plus the `meta.tc` ID seed on `applyOtUpdate` that flips Overleaf's server-side `RangesTracker` into track-changes mode.
+
+## Status
+
+Working end-to-end against `overleaf.com` — 16 tools, tracked-changes edits and review-panel comments both verified. Published on npm as [`@netique/overleaf-mcp`](https://www.npmjs.com/package/@netique/overleaf-mcp).
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `ping` | Health check. Does not contact Overleaf. |
+| `list_projects` | Lists projects on the configured account, sorted by most recently updated. Supports `name_contains`, `include_archived`, `include_trashed`, `limit`. |
+| `open_project` | Joins a project's real-time session and caches its file tree. Returns rich metadata: `root_doc_path`, `compiler`, `spell_check_language`, `public_access_level`, owner + members (with privileges), and whether track-changes is on for your user. |
+| `list_files` | Lists the file tree of the open project (cached, no network). Filter by `kind` and `path_contains`. |
+| `read_file` | Reads a doc (returns text + OT version + a summary of tracked changes / comments) or a binary file (base64 + MIME). `path` is optional — defaults to the project's root doc. |
+| `edit_file` | Replaces a doc's contents. Computes a minimal diff via `diff-match-patch`, submits it as an OT operation, and adds `meta.tc` so the edit lands as a pending suggestion in the Review panel by default. Pass `track: "off"` to write directly or `track: "auto"` to honor the project's track-changes setting. `path` is optional — defaults to the project's root doc. |
+| `list_tracked_changes` | Enumerates every pending tracked-change suggestion across the open project, with author name + email, doc path, op kind (insert/delete), position, op text, change_id. Filter by `author_email`, `author_id_endswith`, `path_contains`, `kind`, `text_contains`, `limit`. |
+| `accept_changes` | Accepts one or more tracked changes by `change_id` (from `list_tracked_changes`). Multi-doc groups are batched automatically. Irreversible. |
+| `reject_changes` | Rejects one or more tracked changes by `change_id`. Implemented as `applyOtUpdate` with the inverse op + `u:true` (same pathway Overleaf's web client uses). Irreversible. |
+| `compile` | Triggers an Overleaf compile and returns a unified summary: `status`, `built_cleanly` (true iff PDF + zero LaTeX errors), `error_count`, `warning_count`, `first_errors` (sample), `output_files`, timings. Already fetches and parses `output.log` inline — no extra `read_log` call needed for the happy path. Pass `root_doc`, `draft`, `stop_on_first_error` to control. |
+| `read_log` | Returns the full `output.log` from the most recent compile, with `!`-prefixed error lines surfaced at the top. Use when `compile`'s inline summary isn't enough context. |
+| `list_comments` | Lists review-panel comment threads with doc path, quoted text, author, latest-message preview. Supports `include_resolved`, `path_contains`, `full`. |
+| `read_comment_thread` | Returns the full message history of one thread. |
+| `reply_comment` | Posts a new message to an existing thread. |
+| `resolve_comment` | Marks a thread resolved. |
+| `reopen_comment` | Reopens a resolved thread. |
+
+## Typical workflow
+
+Things to ask Claude once `overleaf-mcp` is connected:
+
+- _"Accept every pending tracked change by John Doe that's only adjusting punctuation or whitespace."_ — uses `list_tracked_changes(author_email: "...")` → LLM filters by op text → `accept_changes(...)`.
+- _"List my recent Overleaf projects."_
+- _"Open my thesis project and show me what comments my collaborators have left."_
+- _"Read intro.tex and fix the missing comma in the second paragraph."_  → with track-changes on, this lands as a tracked suggestion.
+- _"Compile the project and tell me what the LaTeX errors mean."_  → uses `compile` then `read_log` automatically.
+- _"For each open comment thread, suggest a fix and reply with what you did."_  → end-to-end review workflow.
+
+## Requirements
+
+- Node ≥ 20
+- An Overleaf account (overleaf.com or self-hosted Community Edition)
+
+## Quick start
+
+No local install needed — `npx` fetches and runs the latest version. Add this to your Claude Desktop / Claude Code MCP config:
+
+```json
+{
+  "mcpServers": {
+    "overleaf": {
+      "command": "npx",
+      "args": ["-y", "@netique/overleaf-mcp"],
+      "env": {
+        "OL_BASE_URL": "https://www.overleaf.com",
+        "OL_COOKIE": "overleaf_session2=s%3A...."
+      }
+    }
+  }
+}
+```
+
+For self-hosted Community Edition: set `OL_BASE_URL` to your server (e.g. `https://overleaf.mylab.edu`). Same cookie capture, same tools.
+
+<details>
+<summary>From source (for development)</summary>
+
+```sh
+git clone https://github.com/netique/overleaf-mcp.git
+cd overleaf-mcp
+npm install
+npm run build
+```
+
+Then point your MCP config at the built file:
+
+```json
+{
+  "mcpServers": {
+    "overleaf": {
+      "command": "node",
+      "args": ["/absolute/path/to/overleaf-mcp/dist/index.js"],
+      "env": { "OL_COOKIE": "overleaf_session2=s%3A...." }
+    }
+  }
+}
+```
+</details>
+
+## Authentication
+
+overleaf-mcp authenticates with a session cookie pasted from your browser. The CSRF token is auto-discovered from the `/project` page after login, so you don't need to copy it separately. (Set `OL_CSRF` only if your Overleaf instance doesn't expose the `ol-csrfToken` meta tag.)
+
+### Capturing the cookie
+
+1. Log into Overleaf in your browser.
+2. Open DevTools → **Application** (Chrome/Edge) or **Storage** (Firefox) → **Cookies** → `https://www.overleaf.com`.
+3. Copy the **value** of `overleaf_session2` — it starts with `s%3A` and is long. That's your `OL_COOKIE` (format: `overleaf_session2=s%3A...`).
+
+> ⚠️ The pasted session cookie grants full account access. Treat it like a password — do not commit it, share it, or paste it into shared configs. Cookies expire periodically; if you see auth errors, re-copy.
+
+### Environment variables
+
+| Var | Required | Default | Notes |
+|---|---|---|---|
+| `OL_COOKIE` | yes | — | Session cookie, see above. |
+| `OL_BASE_URL` | no | `https://www.overleaf.com` | Override for self-hosted Overleaf. |
+| `OL_CSRF` | no | auto-discovered | Force a specific CSRF token. Only needed if your server doesn't ship the `ol-csrfToken` meta tag. |
+| `OL_MCP_LOG_LEVEL` | no | `info` | `debug`, `info`, `warn`, `error`. Goes to stderr; stdout is reserved for MCP JSON-RPC. |
+
+## Troubleshooting
+
+**`OverleafAuthError: Session cookie rejected (redirected to /login)`** — your `OL_COOKIE` has expired. Re-copy `overleaf_session2` from DevTools.
+
+**`Socket.IO handshake returned 502`** — Overleaf's load balancer rejected the WebSocket upgrade. Almost always means the cookie was rejected. Same fix as above.
+
+**`Could not find ol-csrfToken meta tag`** — your Overleaf server doesn't expose the CSRF meta tag (rare; mostly very old Community Edition). Set `OL_CSRF` explicitly.
+
+**Edits land but don't show up as tracked suggestions** — confirm track-changes is on for *your user* on this project (Menu → Settings → Track Changes → "For me" or "For everyone"). `open_project` reports the detected state under `track_changes_on_for_me`. To force tracking regardless, pass `track: "on"` to `edit_file`.
+
+**Compile succeeds but `read_log` returns 404** — Overleaf needs `?clsiserverid=...` to route to the right CLSI worker; we add this automatically from the previous compile response. If you see this, the previous compile may not have completed; re-run `compile` and then `read_log`.
+
+## Acknowledgements
+
+- [`overleaf-workshop`](https://github.com/overleaf-workshop/overleaf-workshop) by @iamhyc and contributors — protocol reference for the HTTP + Socket.IO flow, comment thread endpoints. The `94-review-panel` branch was the source for the comment data shapes.
+- [`overleaf/overleaf`](https://github.com/overleaf/overleaf) — `libraries/ranges-tracker/index.cjs` and `services/document-updater/RangesManager.js` are the authoritative source for how tracked changes are emitted (the `update.meta.tc` flag and ID seed format).
+- [`googlecolab/colab-mcp`](https://github.com/googlecolab/colab-mcp) — UX reference for what an agent-friendly MCP into a hosted editor should feel like.
+
+## License
+
+**AGPL-3.0-or-later** — see [`LICENSE`](./LICENSE).
+
+overleaf-mcp incorporates code ported from two AGPL-3.0 projects (overleaf-workshop and overleaf/overleaf — see Acknowledgements), so the combined work is distributed under the same terms. Practical implications:
+
+- You can use, study, and modify overleaf-mcp freely.
+- If you redistribute it, modified or not, recipients must also receive the source under AGPL-3.0.
+- If you run a **modified** version as a network service that users interact with, you must make the modified source available to those users. Running unmodified overleaf-mcp as your own personal MCP server is unaffected.

package/dist/api/commentTypes.js

@@ -0,0 +1,5 @@
+// Review-panel comment threads, ported from the overleaf-workshop 94-review-panel
+// branch (extendedBase.ts). Shapes match what Overleaf's HTTP REST API actually
+// returns; we keep them loose because field set varies a bit by server version.
+export {};
+//# sourceMappingURL=commentTypes.js.map

package/dist/api/commentTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commentTypes.js","sourceRoot":"","sources":["../../src/api/commentTypes.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,gFAAgF;AAChF,gFAAgF"}

package/dist/api/compileTypes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=compileTypes.js.map

package/dist/api/compileTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compileTypes.js","sourceRoot":"","sources":["../../src/api/compileTypes.ts"],"names":[],"mappings":""}

package/dist/api/errors.js

@@ -0,0 +1,17 @@
+export class OverleafAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "OverleafAuthError";
+    }
+}
+export class OverleafApiError extends Error {
+    status;
+    body;
+    constructor(status, body, hint) {
+        super(`Overleaf API error ${status}${hint ? ` (${hint})` : ""}: ${body.slice(0, 200)}`);
+        this.name = "OverleafApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/api/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/api/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,MAAM,CAAS;IACf,IAAI,CAAS;IACtB,YAAY,MAAc,EAAE,IAAY,EAAE,IAAa;QACrD,KAAK,CAAC,sBAAsB,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACxF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/api/http.js

@@ -0,0 +1,52 @@
+import { getIdentity } from "../session/identity.js";
+import { OverleafApiError } from "./errors.js";
+function joinUrl(base, path) {
+    return `${base}/${path.replace(/^\/+/, "")}`;
+}
+export async function olGet(path, extraHeaders = {}) {
+    const id = await getIdentity();
+    return fetch(joinUrl(id.baseUrl, path), {
+        method: "GET",
+        redirect: "manual",
+        headers: { Cookie: id.cookie, Connection: "keep-alive", ...extraHeaders },
+    });
+}
+export async function olPostJson(path, body = {}, extraHeaders = {}) {
+    const id = await getIdentity();
+    return fetch(joinUrl(id.baseUrl, path), {
+        method: "POST",
+        redirect: "manual",
+        headers: {
+            Cookie: id.cookie,
+            Connection: "keep-alive",
+            "Content-Type": "application/json",
+            "X-Csrf-Token": id.csrf,
+            ...extraHeaders,
+        },
+        body: JSON.stringify({ _csrf: id.csrf, ...body }),
+    });
+}
+export async function olDelete(path, extraHeaders = {}) {
+    const id = await getIdentity();
+    return fetch(joinUrl(id.baseUrl, path), {
+        method: "DELETE",
+        redirect: "manual",
+        headers: {
+            Cookie: id.cookie,
+            Connection: "keep-alive",
+            "X-Csrf-Token": id.csrf,
+            ...extraHeaders,
+        },
+    });
+}
+export async function expectOk(res, hint) {
+    if (res.ok)
+        return res;
+    const body = await res.text().catch(() => "");
+    throw new OverleafApiError(res.status, body, hint);
+}
+export async function asJson(res, hint) {
+    await expectOk(res, hint);
+    return (await res.json());
+}
+//# sourceMappingURL=http.js.map

package/dist/api/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/api/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,SAAS,OAAO,CAAC,IAAY,EAAE,IAAY;IACzC,OAAO,GAAG,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;AAC/C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,IAAY,EAAE,eAAuC,EAAE;IACjF,MAAM,EAAE,GAAG,MAAM,WAAW,EAAE,CAAC;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE;QACtC,MAAM,EAAE,KAAK;QACb,QAAQ,EAAE,QAAQ;QAClB,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE;KAC1E,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAAY,EACZ,OAAgC,EAAE,EAClC,eAAuC,EAAE;IAEzC,MAAM,EAAE,GAAG,MAAM,WAAW,EAAE,CAAC;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE;QACtC,MAAM,EAAE,MAAM;QACd,QAAQ,EAAE,QAAQ;QAClB,OAAO,EAAE;YACP,MAAM,EAAE,EAAE,CAAC,MAAM;YACjB,UAAU,EAAE,YAAY;YACxB,cAAc,EAAE,kBAAkB;YAClC,cAAc,EAAE,EAAE,CAAC,IAAI;YACvB,GAAG,YAAY;SAChB;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;KAClD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY,EAAE,eAAuC,EAAE;IACpF,MAAM,EAAE,GAAG,MAAM,WAAW,EAAE,CAAC;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE;QACtC,MAAM,EAAE,QAAQ;QAChB,QAAQ,EAAE,QAAQ;QAClB,OAAO,EAAE;YACP,MAAM,EAAE,EAAE,CAAC,MAAM;YACjB,UAAU,EAAE,YAAY;YACxB,cAAc,EAAE,EAAE,CAAC,IAAI;YACvB,GAAG,YAAY;SAChB;KACF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAa,EAAE,IAAa;IACzD,IAAI,GAAG,CAAC,EAAE;QAAE,OAAO,GAAG,CAAC;IACvB,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAC9C,MAAM,IAAI,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,MAAM,CAAc,GAAa,EAAE,IAAa;IACpE,MAAM,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1B,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAM,CAAC;AACjC,CAAC"}

package/dist/api/projectTypes.js

@@ -0,0 +1,38 @@
+// Shapes returned by Overleaf's joinProject / joinDoc Socket.IO events.
+// Field names match what the server emits — keep raw, normalize in tools.
+export function flattenTree(root, prefix = "") {
+    const out = [];
+    for (const folder of root.folders) {
+        const path = prefix ? `${prefix}/${folder.name}` : folder.name;
+        out.push({ kind: "folder", id: folder._id, path, name: folder.name, parentFolderId: root._id });
+        out.push(...flattenTree(folder, path));
+    }
+    for (const doc of root.docs) {
+        const path = prefix ? `${prefix}/${doc.name}` : doc.name;
+        out.push({ kind: "doc", id: doc._id, path, name: doc.name, parentFolderId: root._id });
+    }
+    for (const file of root.fileRefs) {
+        const path = prefix ? `${prefix}/${file.name}` : file.name;
+        out.push({ kind: "file", id: file._id, path, name: file.name, parentFolderId: root._id });
+    }
+    return out;
+}
+export function isTrackChangesOnForUser(project, userId) {
+    const state = project.track_changes_state ?? project.trackChangesState;
+    if (state === undefined || state === null)
+        return false;
+    if (typeof state === "boolean")
+        return state;
+    if (typeof state === "object") {
+        const m = state;
+        if (m[userId] === true)
+            return true;
+        if (m["__guests__"] === true)
+            return true;
+        // Some Overleaf builds use the value true on key '__everyone__' or 'all'.
+        if (m["__everyone__"] === true)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=projectTypes.js.map

package/dist/api/projectTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectTypes.js","sourceRoot":"","sources":["../../src/api/projectTypes.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,0EAA0E;AA6D1E,MAAM,UAAU,WAAW,CAAC,IAAkB,EAAE,MAAM,GAAG,EAAE;IACzD,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;QAC/D,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAChG,GAAG,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;IACzC,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;QACzD,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAC3D,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC5F,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,OAAsB,EAAE,MAAc;IAC5E,MAAM,KAAK,GAAG,OAAO,CAAC,mBAAmB,IAAI,OAAO,CAAC,iBAAiB,CAAC;IACvE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACxD,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,KAAgC,CAAC;QAC3C,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACpC,IAAI,CAAC,CAAC,YAAY,CAAC,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC1C,0EAA0E;QAC1E,IAAI,CAAC,CAAC,cAAc,CAAC,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;IAC9C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/api/socket.js

@@ -0,0 +1,348 @@
+// Minimal Socket.IO 0.9 client tailored for Overleaf.
+//
+// Overleaf's bundled `socket.io-client@0.9.17-overleaf-N` fork accepts an
+// `extraHeaders` option but never forwards it to either transport — XMLHttpRequest
+// forbids the `Cookie` header and the WebSocket transport calls
+// `new WebSocket(url)` with no header argument. That makes the fork unusable
+// against overleaf.com from a server-side caller. We instead speak the wire
+// protocol ourselves: handshake via `fetch` (cookies propagate naturally),
+// upgrade via `ws@8` (which supports a `headers` option).
+//
+// Protocol reference: https://github.com/learnboost/socket.io-spec (v0.9.x)
+// Frame format: `<type>:<id>:<endpoint>:<data>`
+//   0 disconnect | 1 connect | 2 heartbeat | 3 message | 4 json
+//   5 event { name, args } | 6 ack `:::<id>+<json>` | 7 error
+//
+// We only implement the subset Overleaf actually emits.
+import WebSocket from "ws";
+import { OverleafApiError, OverleafAuthError } from "./errors.js";
+import { getIdentity } from "../session/identity.js";
+import { logger } from "../util/logger.js";
+function decodePackedUtf8(line) {
+    return Buffer.from(line, "latin1").toString("utf8");
+}
+class OverleafSocket {
+    projectId;
+    identity;
+    ws = null;
+    nextAckId = 1;
+    pending = new Map();
+    listeners = new Map();
+    heartbeatInterval = 60_000;
+    heartbeatTimer = null;
+    closed = false;
+    joinedProject = null;
+    publicId = null;
+    permissionsLevel = null;
+    protocolVersion = null;
+    constructor(projectId, identity) {
+        this.projectId = projectId;
+        this.identity = identity;
+    }
+    async connect(timeoutMs = 15_000) {
+        const base = this.identity.baseUrl;
+        const t = Date.now();
+        const hsUrl = `${base}/socket.io/1/?projectId=${encodeURIComponent(this.projectId)}&t=${t}`;
+        const hsRes = await fetch(hsUrl, {
+            method: "GET",
+            redirect: "manual",
+            headers: {
+                Cookie: this.identity.cookie,
+                Origin: new URL(base).origin,
+                Connection: "keep-alive",
+            },
+        });
+        if (hsRes.status !== 200) {
+            const body = await hsRes.text().catch(() => "");
+            throw new OverleafAuthError(`Socket.IO handshake returned ${hsRes.status}: ${body.slice(0, 200)}`);
+        }
+        const hsBody = await hsRes.text();
+        const [sid, hbStr, , transports] = hsBody.split(":");
+        if (!sid || !transports?.includes("websocket")) {
+            throw new OverleafApiError(0, hsBody, "handshake response did not include a sid or websocket transport");
+        }
+        this.heartbeatInterval = Math.max(15_000, (Number(hbStr) || 60) * 1000 - 5_000);
+        const wsUrl = `${base.replace(/^http/, "ws")}/socket.io/1/websocket/${sid}`;
+        const ws = new WebSocket(wsUrl, {
+            headers: { Cookie: this.identity.cookie, Origin: new URL(base).origin },
+            handshakeTimeout: timeoutMs,
+        });
+        this.ws = ws;
+        await new Promise((resolve, reject) => {
+            const settleTimer = setTimeout(() => reject(new OverleafApiError(0, "", `WebSocket upgrade did not complete within ${timeoutMs}ms`)), timeoutMs);
+            ws.once("open", () => {
+                clearTimeout(settleTimer);
+                logger.info(`socket.io connected (sid=${sid})`);
+                this.startHeartbeats();
+                // joinProjectResponse arrives auto-magically on v2-style URL.
+                const once = (args) => {
+                    const payload = args[0];
+                    if (payload) {
+                        this.joinedProject = payload.project ?? null;
+                        this.publicId = payload.publicId ?? null;
+                        this.permissionsLevel = payload.permissionsLevel ?? null;
+                        this.protocolVersion = payload.protocolVersion ?? null;
+                    }
+                    resolve();
+                };
+                this.once("joinProjectResponse", once);
+                // Some servers (older / v1 path) won't emit joinProjectResponse on the
+                // initial WS connect; fall back to emitting joinProject explicitly.
+                setTimeout(() => {
+                    if (!this.joinedProject) {
+                        logger.info("no joinProjectResponse received, falling back to explicit joinProject emit");
+                        this.emit("joinProject", [{ project_id: this.projectId }])
+                            .then((ret) => {
+                            const tuple = Array.isArray(ret) ? ret : [ret];
+                            const [project, perm, proto] = tuple;
+                            this.joinedProject = project ?? null;
+                            this.permissionsLevel = perm ?? null;
+                            this.protocolVersion = typeof proto === "number" ? proto : null;
+                            resolve();
+                        })
+                            .catch(reject);
+                    }
+                }, 3_000);
+            });
+            ws.once("error", (err) => {
+                clearTimeout(settleTimer);
+                reject(err instanceof Error ? err : new Error(String(err)));
+            });
+            ws.on("message", (data) => this.handleFrame(data.toString("utf8")));
+            ws.once("close", (code, reason) => {
+                this.stopHeartbeats();
+                this.closed = true;
+                const r = reason?.toString?.() ?? "";
+                logger.warn(`socket closed code=${code} reason=${r}`);
+                for (const [, p] of this.pending) {
+                    clearTimeout(p.timer);
+                    p.reject(new Error(`socket closed (${code}) ${r}`));
+                }
+                this.pending.clear();
+            });
+        });
+    }
+    startHeartbeats() {
+        this.heartbeatTimer = setInterval(() => {
+            if (this.ws?.readyState === WebSocket.OPEN) {
+                try {
+                    this.ws.send("2::");
+                }
+                catch { /* ignore */ }
+            }
+        }, this.heartbeatInterval);
+    }
+    stopHeartbeats() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+    }
+    handleFrame(frame) {
+        if (!frame)
+            return;
+        // Parse `<type>:<id>:<endpoint>:<data>`. Data may contain colons, so split
+        // only on the first three.
+        const m = frame.match(/^(\d+):([^:]*):([^:]*):?([\s\S]*)$/);
+        if (!m) {
+            logger.debug("ignoring unparseable frame", frame.slice(0, 120));
+            return;
+        }
+        const type = m[1];
+        const id = m[2];
+        const data = m[4];
+        switch (type) {
+            case "0": // disconnect
+                logger.warn("server sent disconnect frame");
+                try {
+                    this.ws?.close();
+                }
+                catch { /* ignore */ }
+                return;
+            case "1": // connect ack — usually with empty endpoint
+                return;
+            case "2": // heartbeat from server, echo back
+                try {
+                    this.ws?.send("2::");
+                }
+                catch { /* ignore */ }
+                return;
+            case "5": {
+                // Event: `5:<id>[+]::{"name":"event","args":[...]}`
+                let obj = {};
+                try {
+                    obj = JSON.parse(data);
+                }
+                catch {
+                    return;
+                }
+                const name = obj.name;
+                if (!name)
+                    return;
+                const args = obj.args ?? [];
+                const ls = this.listeners.get(name);
+                if (ls)
+                    for (const l of ls)
+                        try {
+                            l(args);
+                        }
+                        catch (e) {
+                            logger.error(`listener for ${name} threw`, e);
+                        }
+                // Track-changes / reciveNewDoc / etc may also acknowledge with msg id;
+                // we ignore that for now since Overleaf doesn't appear to expect a
+                // response from us for server-emitted events.
+                return;
+            }
+            case "6": {
+                // ACK: `6:::<id>[+<data_json>]`. Note: the "id" field above will be
+                // empty for an ack frame; the ack id is at the start of `data`.
+                const plus = data.indexOf("+");
+                const ackIdStr = plus >= 0 ? data.slice(0, plus) : data;
+                const ackDataRaw = plus >= 0 ? data.slice(plus + 1) : "";
+                const ackId = Number(ackIdStr);
+                const pending = this.pending.get(ackId);
+                if (!pending)
+                    return;
+                this.pending.delete(ackId);
+                clearTimeout(pending.timer);
+                let arr = [];
+                if (ackDataRaw) {
+                    try {
+                        arr = JSON.parse(ackDataRaw);
+                    }
+                    catch {
+                        arr = [ackDataRaw];
+                    }
+                    if (!Array.isArray(arr))
+                        arr = [arr];
+                }
+                // Overleaf's ack convention: first element is the error (null on
+                // success); remaining elements are the result.
+                const err = arr[0];
+                if (err)
+                    pending.reject(err instanceof Error ? err : new Error(typeof err === "string" ? err : JSON.stringify(err)));
+                else
+                    pending.resolve(arr.slice(1));
+                return;
+            }
+            case "7": {
+                // Error
+                logger.error("server error frame", data);
+                for (const [, p] of this.pending) {
+                    clearTimeout(p.timer);
+                    p.reject(new Error(`server error: ${data}`));
+                }
+                this.pending.clear();
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    on(event, listener) {
+        const arr = this.listeners.get(event) ?? [];
+        arr.push(listener);
+        this.listeners.set(event, arr);
+    }
+    once(event, listener) {
+        const wrap = (args) => {
+            this.off(event, wrap);
+            listener(args);
+        };
+        this.on(event, wrap);
+    }
+    off(event, listener) {
+        const arr = this.listeners.get(event);
+        if (!arr)
+            return;
+        const i = arr.indexOf(listener);
+        if (i >= 0)
+            arr.splice(i, 1);
+    }
+    async emit(name, args = [], timeoutMs = 15_000) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new OverleafApiError(0, "", "socket not open");
+        }
+        const ackId = this.nextAckId++;
+        const frame = `5:${ackId}+::${JSON.stringify({ name, args })}`;
+        return await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(ackId);
+                reject(new Error(`event '${name}' timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(ackId, {
+                resolve: (data) => resolve((data.length <= 1 ? data[0] : data)),
+                reject,
+                timer,
+            });
+            try {
+                this.ws.send(frame);
+            }
+            catch (e) {
+                clearTimeout(timer);
+                this.pending.delete(ackId);
+                reject(e instanceof Error ? e : new Error(String(e)));
+            }
+        });
+    }
+    isOpen() {
+        return !this.closed && this.ws?.readyState === WebSocket.OPEN;
+    }
+    disconnect() {
+        this.stopHeartbeats();
+        if (this.ws) {
+            try {
+                this.ws.close();
+            }
+            catch { /* ignore */ }
+            this.ws = null;
+        }
+        this.closed = true;
+    }
+}
+let active = null;
+export async function ensureSocketForProject(projectId) {
+    if (active && active.projectId === projectId && active.isOpen()) {
+        return { socket: active, publicId: active.publicId ?? undefined, joinedProject: active.joinedProject ?? undefined };
+    }
+    if (active) {
+        logger.info(`switching project: ${active.projectId} -> ${projectId}`);
+        active.disconnect();
+        active = null;
+    }
+    const identity = await getIdentity();
+    const s = new OverleafSocket(projectId, identity);
+    await s.connect();
+    active = s;
+    return { socket: s, publicId: s.publicId ?? undefined, joinedProject: s.joinedProject ?? undefined };
+}
+export function getActiveSocket() {
+    return active;
+}
+export async function joinDoc(docId) {
+    if (!active)
+        throw new OverleafApiError(0, "", "no active project — call open_project first");
+    // The ack returns `[docLinesAscii, version, updates, ranges]`.
+    const ret = await active.emit("joinDoc", [docId, { encodeRanges: true }]);
+    const tuple = Array.isArray(ret) ? ret : [ret];
+    const [docLinesAscii, version, updates, ranges] = tuple;
+    const docLines = (docLinesAscii ?? []).map(decodePackedUtf8);
+    return { docLines, version: version ?? 0, updates: updates ?? [], ranges };
+}
+export async function leaveDoc(docId) {
+    if (!active)
+        return;
+    await active.emit("leaveDoc", [docId]).catch(() => undefined);
+}
+export async function applyOtUpdate(docId, update) {
+    if (!active)
+        throw new OverleafApiError(0, "", "no active project — call open_project first");
+    await active.emit("applyOtUpdate", [docId, update]);
+}
+export function disconnectActive() {
+    if (active) {
+        active.disconnect();
+        active = null;
+    }
+}
+//# sourceMappingURL=socket.js.map