24264efa25
8-point multi-aspect review of the batch PR; security/regressions were clean. 1. Lease leak: the #180 reorder moved `toolsFor` (which leases external MCP clients, refCount+1) ahead of buildSystemPrompt + forUser, but the only release (closeExternalClients) was bound to the streamText callbacks. A throw in between leaked the lease (refCount stuck, undici sockets held until restart). Define closeExternalClients right after the lease and wrap buildSystemPrompt+forUser in try/catch that closes-then-rethrows. 2. Cover the patch_node/delete_node dup-id refusal (#159 #6): extract the guard into a pure `assertUnambiguousMatch` (node-ops) and unit-test 0/1/>1. 3. Regress the body-before-title order (#159 #10): mock-HTTP test (collab fails fast against a server with no WS upgrade) asserts /pages/update (title) is NEVER posted when the body write fails — for updatePage AND updatePageJson. 4. CHANGELOG [Unreleased]: #180, #168 (Added); #163 (Fixed). 5. Add the missing en-US i18n keys (Back to references / {{label}}). 6. Drop the duplicate content/empty/blank cases in ai-chat.prompt.spec.ts (they repeat the buildMcpToolingBlock unit tests); keep only sandwich placement + both-safety-copies. 7. CI Postgres pg16 -> pg18 (match docker-compose). 8. jsonb decode seam: shared `parseJsonbValue(value, guard)` in database/utils.ts holds the legacy double-encoding self-heal in one place; parseToolAllowlist / parseModelConfig keep only a type-guard. Verified: server build + 124 unit + 15 integration; mcp 311; prettier clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2527 lines
119 KiB
JavaScript
2527 lines
119 KiB
JavaScript
import FormData from "form-data";
|
|
import axios from "axios";
|
|
import { basename, extname } from "path";
|
|
import { filterWorkspace, filterSpace, filterPage, filterComment, filterSearchResult, } from "./lib/filters.js";
|
|
import { HocuspocusProvider } from "@hocuspocus/provider";
|
|
import { TiptapTransformer } from "@hocuspocus/transformer";
|
|
import * as Y from "yjs";
|
|
import WebSocket from "ws";
|
|
import { convertProseMirrorToMarkdown } from "./lib/markdown-converter.js";
|
|
import { updatePageContentRealtime, replacePageContent, markdownToProseMirror, mutatePageContent, buildCollabWsUrl, assertYjsEncodable, applyDocToFragment, } from "./lib/collaboration.js";
|
|
import { footnoteWarningsField } from "./lib/footnote-analyze.js";
|
|
import { buildPageTree } from "./lib/tree.js";
|
|
import { serializeDocmostMarkdown, parseDocmostMarkdown, } from "./lib/markdown-document.js";
|
|
import { replaceNodeById, deleteNodeById, assertUnambiguousMatch, insertNodeRelative, buildOutline, getNodeByRef, readTable, insertTableRow, deleteTableRow, updateTableCell, } from "./lib/node-ops.js";
|
|
import { withPageLock } from "./lib/page-lock.js";
|
|
import { applyTextEdits, } from "./lib/json-edit.js";
|
|
import { getCollabToken, performLogin } from "./lib/auth-utils.js";
|
|
import { diffDocs, summarizeChange } from "./lib/diff.js";
|
|
import { applyAnchorInDoc, canAnchorInDoc } from "./lib/comment-anchor.js";
|
|
import { blockText, walk, getList, insertMarkerAfter, setCalloutRange, noteItem, mdToInlineNodes, commentsToFootnotes, } from "./lib/transforms.js";
|
|
import vm from "node:vm";
|
|
// Supported image types, kept as two lookup tables so both a local file
|
|
// extension and a remote Content-Type can be mapped to the same canonical set.
|
|
const EXT_TO_MIME = {
|
|
".png": "image/png",
|
|
".jpg": "image/jpeg",
|
|
".jpeg": "image/jpeg",
|
|
".gif": "image/gif",
|
|
".webp": "image/webp",
|
|
".svg": "image/svg+xml",
|
|
};
|
|
const MIME_TO_EXT = {
|
|
"image/png": ".png",
|
|
"image/jpeg": ".jpg",
|
|
"image/gif": ".gif",
|
|
"image/webp": ".webp",
|
|
"image/svg+xml": ".svg",
|
|
};
|
|
export class DocmostClient {
|
|
client;
|
|
token = null;
|
|
apiUrl;
|
|
// email/password are only set on the service-account (credentials) variant;
|
|
// null on the getToken variant (where there are no credentials to log in with).
|
|
email = null;
|
|
password = null;
|
|
// Per-user token provider. When set, login() calls it to obtain a BARE access
|
|
// JWT instead of performLogin, and the 401/403 re-auth path re-calls it.
|
|
getTokenFn = null;
|
|
// Optional collab-token provider. When set, getCollabTokenWithReauth() returns
|
|
// its token instead of calling POST /auth/collab-token; on a 401/403 it is
|
|
// re-invoked once. Used by the internal agent to carry signed provenance.
|
|
getCollabTokenFn = null;
|
|
// In-flight login dedup: when the token expires, the 401 interceptor,
|
|
// ensureAuthenticated, getCollabTokenWithReauth and the two multipart retries
|
|
// can all call login() at once. Memoizing a single promise collapses that
|
|
// thundering herd into ONE /auth/login request that everyone awaits.
|
|
loginPromise = null;
|
|
constructor(configOrBaseURL, email, password) {
|
|
// Normalize the legacy positional form into the object union.
|
|
const config = typeof configOrBaseURL === "string"
|
|
? { apiUrl: configOrBaseURL, email: email, password: password }
|
|
: configOrBaseURL;
|
|
this.apiUrl = config.apiUrl;
|
|
if ("getToken" in config) {
|
|
// Token variant: carry the user's JWT via getToken; no credentials, so
|
|
// login() must never call performLogin (there is nothing to log in with).
|
|
this.getTokenFn = config.getToken;
|
|
}
|
|
else {
|
|
// Service-account variant: behaves exactly as before (performLogin).
|
|
this.email = config.email;
|
|
this.password = config.password;
|
|
}
|
|
// Optional, available to both variants. When present, content mutations get
|
|
// their collab token from here instead of POST /auth/collab-token.
|
|
if (config.getCollabToken) {
|
|
this.getCollabTokenFn = config.getCollabToken;
|
|
}
|
|
this.client = axios.create({
|
|
baseURL: this.apiUrl,
|
|
// Default request timeout so a hung connection cannot wedge a per-page
|
|
// lock or block the server indefinitely. Multipart uploads override this
|
|
// with a longer per-request timeout.
|
|
timeout: 30000,
|
|
headers: {
|
|
"Content-Type": "application/json",
|
|
},
|
|
});
|
|
// Re-authenticate transparently on a 401/403 once: the JWT authToken can
|
|
// expire while the server is long-running, after which every cached-token
|
|
// request would otherwise fail until a manual restart. On such a response,
|
|
// clear the stale token, perform a fresh login, and replay the original
|
|
// request exactly once (guarded by config._retry to avoid infinite loops;
|
|
// the login request itself is never retried).
|
|
this.client.interceptors.response.use((response) => response, async (error) => {
|
|
const config = error.config;
|
|
const status = error.response?.status;
|
|
const isAuthError = status === 401 || status === 403;
|
|
const isLoginRequest = typeof config?.url === "string" && config.url.includes("/auth/login");
|
|
if (config && isAuthError && !config._retry && !isLoginRequest) {
|
|
config._retry = true;
|
|
// Drop the stale token + Authorization header before re-login.
|
|
this.token = null;
|
|
delete this.client.defaults.headers.common["Authorization"];
|
|
try {
|
|
await this.login();
|
|
}
|
|
catch (loginError) {
|
|
// Re-login failed: surface the original error to the caller.
|
|
return Promise.reject(error);
|
|
}
|
|
// Re-issue the original request with the freshly minted Bearer token.
|
|
// Read it from the default header that login() just set, not from
|
|
// this.token, to avoid a theoretical "Bearer null" if this.token was
|
|
// cleared between login() resolving and this point.
|
|
config.headers = config.headers || {};
|
|
config.headers["Authorization"] =
|
|
this.client.defaults.headers.common["Authorization"];
|
|
return this.client.request(config);
|
|
}
|
|
return Promise.reject(error);
|
|
});
|
|
}
|
|
/** Application base URL (API URL without the /api suffix). */
|
|
get appUrl() {
|
|
return this.apiUrl.replace(/\/api\/?$/, "");
|
|
}
|
|
async login() {
|
|
// Reuse an in-flight login if one is already running so concurrent callers
|
|
// share a single token fetch instead of each issuing their own.
|
|
if (!this.loginPromise) {
|
|
// Token variant: re-fetch a BARE JWT via getToken() (there are no
|
|
// credentials to log in with — on a 401/403 the interceptor below calls
|
|
// login() again, which re-invokes getToken()). Credentials variant:
|
|
// performLogin against /auth/login exactly as before.
|
|
const fetchToken = this.getTokenFn
|
|
? this.getTokenFn()
|
|
: performLogin(this.apiUrl, this.email, this.password);
|
|
this.loginPromise = fetchToken
|
|
.then((token) => {
|
|
// Guard against an empty/invalid token (e.g. a getToken provider that
|
|
// resolves to "" or null): without this an empty token would set a
|
|
// literal "Authorization: Bearer null"/"Bearer " header and every
|
|
// request would 401 with a confusing error. Fail loudly instead.
|
|
if (typeof token !== "string" || token.length === 0) {
|
|
throw new Error("getToken returned an empty token");
|
|
}
|
|
this.token = token;
|
|
this.client.defaults.headers.common["Authorization"] =
|
|
`Bearer ${token}`;
|
|
})
|
|
.finally(() => {
|
|
this.loginPromise = null;
|
|
});
|
|
}
|
|
return this.loginPromise;
|
|
}
|
|
async ensureAuthenticated() {
|
|
if (!this.token) {
|
|
await this.login();
|
|
}
|
|
}
|
|
/**
|
|
* Fetch a collaboration token, transparently re-authenticating once on a
|
|
* 401/403. getCollabToken() uses bare axios internally, so it is NOT covered
|
|
* by this.client's response interceptor; this helper replicates that
|
|
* behaviour for collab-token requests: ensure a token, try once, and on an
|
|
* expired-token auth error perform a fresh login and retry exactly once.
|
|
*/
|
|
async getCollabTokenWithReauth() {
|
|
// Collab-token PROVIDER path: when a getCollabToken provider was supplied
|
|
// (the internal agent's provenance collab token), use it instead of the
|
|
// REST /auth/collab-token endpoint. Re-invoke it once on a 401/403 (e.g. the
|
|
// signed token expired between content mutations in a long agent turn).
|
|
if (this.getCollabTokenFn) {
|
|
try {
|
|
const token = await this.getCollabTokenFn();
|
|
if (typeof token !== "string" || token.length === 0) {
|
|
throw new Error("getCollabToken returned an empty token");
|
|
}
|
|
return token;
|
|
}
|
|
catch (e) {
|
|
const axiosStatus = axios.isAxiosError(e)
|
|
? e.response?.status
|
|
: undefined;
|
|
const attachedStatus = e?.status;
|
|
const isAuthError = axiosStatus === 401 ||
|
|
axiosStatus === 403 ||
|
|
attachedStatus === 401 ||
|
|
attachedStatus === 403;
|
|
if (isAuthError) {
|
|
const token = await this.getCollabTokenFn();
|
|
if (typeof token !== "string" || token.length === 0) {
|
|
throw new Error("getCollabToken returned an empty token");
|
|
}
|
|
return token;
|
|
}
|
|
throw e;
|
|
}
|
|
}
|
|
await this.ensureAuthenticated();
|
|
try {
|
|
return await getCollabToken(this.apiUrl, this.token);
|
|
}
|
|
catch (e) {
|
|
// getCollabToken wraps the AxiosError in a plain Error but attaches the
|
|
// HTTP status as `.status`, so detect an auth failure via either the raw
|
|
// AxiosError shape OR the attached status.
|
|
const axiosStatus = axios.isAxiosError(e)
|
|
? e.response?.status
|
|
: undefined;
|
|
const attachedStatus = e?.status;
|
|
const isAuthError = axiosStatus === 401 ||
|
|
axiosStatus === 403 ||
|
|
attachedStatus === 401 ||
|
|
attachedStatus === 403;
|
|
if (isAuthError) {
|
|
await this.login();
|
|
return await getCollabToken(this.apiUrl, this.token);
|
|
}
|
|
throw e;
|
|
}
|
|
}
|
|
/**
|
|
* Connect to the collaboration websocket, read the live doc, apply
|
|
* `transform`, write the result, and wait for the server to persist it —
|
|
* WITHOUT acquiring the per-page lock.
|
|
*
|
|
* This mirrors collaboration.mutatePageContent EXCEPT that it does not call
|
|
* withPageLock. It exists solely so replaceImage can hold ONE withPageLock
|
|
* across its scan -> upload -> write sequence: the per-page mutex is NOT
|
|
* reentrant, so calling the normal (self-locking) mutatePageContent inside an
|
|
* outer withPageLock for the same pageId would deadlock. The caller MUST hold
|
|
* the page lock for the whole operation; this helper assumes that invariant.
|
|
*
|
|
* `transform` receives the live ProseMirror doc and returns the NEW full doc
|
|
* to write, or `null` to abort with no write. Errors thrown by `transform`
|
|
* propagate to the caller.
|
|
*
|
|
* Resolves a `MutationResult { doc, verify }` mirroring mutatePageContent, so
|
|
* every content mutator (including replaceImage) can return a verifiable
|
|
* change report. The report is computed AFTER the atomic read->write and
|
|
* never throws.
|
|
*/
|
|
mutateLiveContentUnlocked(pageId, collabToken, transform) {
|
|
const CONNECT_TIMEOUT_MS = 25000;
|
|
const PERSIST_TIMEOUT_MS = 20000;
|
|
const ydoc = new Y.Doc();
|
|
const wsUrl = buildCollabWsUrl(this.apiUrl);
|
|
return new Promise((resolve, reject) => {
|
|
let provider;
|
|
let applied = false; // onSynced may fire again on reconnect — apply once.
|
|
let settled = false;
|
|
let connectionLost = false;
|
|
let connectTimer;
|
|
let persistTimer;
|
|
let unsyncedHandler;
|
|
// The verifiable result resolved on every success/abort path. Set on abort
|
|
// (no-op report) and after a real write (computed change report).
|
|
let mutationResult;
|
|
const cleanup = () => {
|
|
if (connectTimer)
|
|
clearTimeout(connectTimer);
|
|
if (persistTimer)
|
|
clearTimeout(persistTimer);
|
|
if (provider) {
|
|
if (unsyncedHandler) {
|
|
try {
|
|
provider.off("unsyncedChanges", unsyncedHandler);
|
|
}
|
|
catch (err) { }
|
|
}
|
|
try {
|
|
provider.destroy();
|
|
}
|
|
catch (err) { }
|
|
}
|
|
};
|
|
const finish = (err, value) => {
|
|
if (settled)
|
|
return;
|
|
settled = true;
|
|
cleanup();
|
|
if (err)
|
|
reject(err);
|
|
else
|
|
resolve(value);
|
|
};
|
|
connectTimer = setTimeout(() => {
|
|
finish(new Error("Connection timeout to collaboration server"));
|
|
}, CONNECT_TIMEOUT_MS);
|
|
const waitForPersistence = () => {
|
|
if (settled)
|
|
return;
|
|
if (!provider) {
|
|
finish(new Error("collab provider gone before persistence"));
|
|
return;
|
|
}
|
|
if (provider.unsyncedChanges === 0) {
|
|
finish(null, mutationResult);
|
|
return;
|
|
}
|
|
persistTimer = setTimeout(() => {
|
|
finish(new Error("Timeout waiting for collaboration server to persist the update"));
|
|
}, PERSIST_TIMEOUT_MS);
|
|
unsyncedHandler = (data) => {
|
|
if (data.number === 0 && !connectionLost) {
|
|
finish(null, mutationResult);
|
|
}
|
|
};
|
|
provider.on("unsyncedChanges", unsyncedHandler);
|
|
};
|
|
provider = new HocuspocusProvider({
|
|
url: wsUrl,
|
|
name: `page.${pageId}`,
|
|
document: ydoc,
|
|
token: collabToken,
|
|
// @ts-ignore - Required for Node.js environment
|
|
WebSocketPolyfill: WebSocket,
|
|
onDisconnect: () => {
|
|
connectionLost = true;
|
|
finish(new Error("Collaboration connection closed before the update was persisted/synced"));
|
|
},
|
|
onClose: () => {
|
|
connectionLost = true;
|
|
finish(new Error("Collaboration connection closed before the update was persisted/synced"));
|
|
},
|
|
onSynced: () => {
|
|
if (applied || settled)
|
|
return;
|
|
applied = true;
|
|
// CRITICAL: keep everything between reading and writing the live doc
|
|
// synchronous (no await) so no remote update can interleave.
|
|
let newDoc;
|
|
let beforeDoc;
|
|
try {
|
|
let liveDoc = TiptapTransformer.fromYdoc(ydoc, "default");
|
|
if (!liveDoc ||
|
|
typeof liveDoc !== "object" ||
|
|
!Array.isArray(liveDoc.content)) {
|
|
liveDoc = { type: "doc", content: [] };
|
|
}
|
|
// Snapshot the before-doc for the change report (safe deep clone).
|
|
beforeDoc = JSON.parse(JSON.stringify(liveDoc));
|
|
newDoc = transform(liveDoc);
|
|
if (newDoc == null) {
|
|
// Transform aborted — write nothing, return the live doc with a
|
|
// no-op change report.
|
|
mutationResult = {
|
|
doc: liveDoc,
|
|
verify: {
|
|
changed: false,
|
|
textInserted: 0,
|
|
textDeleted: 0,
|
|
blocksChanged: 0,
|
|
marks: {},
|
|
summary: "no changes (transform aborted)",
|
|
},
|
|
};
|
|
finish(null, mutationResult);
|
|
return;
|
|
}
|
|
// Structural diff into the live fragment (issue #152), mirroring
|
|
// the main write path: preserves the Yjs ids of unchanged nodes so
|
|
// an open editor's cursor is not yanked to the end of the document.
|
|
// The previous destructive rewrite (delete-all + applyUpdate of a
|
|
// fresh Y.Doc) discarded every node id, so replaceImage — the only
|
|
// caller of this method — still reproduced the #152 cursor jump
|
|
// (#164). applyDocToFragment runs its own atomic `transact`.
|
|
applyDocToFragment(ydoc, newDoc);
|
|
}
|
|
catch (e) {
|
|
finish(e instanceof Error ? e : new Error(String(e)));
|
|
return;
|
|
}
|
|
// Compute the verifiable change report AFTER the transact write: it
|
|
// only needs the JSON before/after, so it cannot affect the atomic
|
|
// read->write window, and summarizeChange never throws.
|
|
mutationResult = {
|
|
doc: newDoc,
|
|
verify: summarizeChange(beforeDoc, newDoc),
|
|
};
|
|
waitForPersistence();
|
|
},
|
|
onAuthenticationFailed: () => {
|
|
finish(new Error("Authentication failed for collaboration connection"));
|
|
},
|
|
});
|
|
});
|
|
}
|
|
/**
|
|
* Generic pagination handler for Docmost API endpoints
|
|
*/
|
|
async paginateAll(endpoint, basePayload = {}, limit = 100) {
|
|
await this.ensureAuthenticated();
|
|
const clampedLimit = Math.max(1, Math.min(100, limit));
|
|
// Hard ceiling on the number of pages to fetch: guards against a server
|
|
// that returns a perpetually-true hasNextPage (which would otherwise loop
|
|
// forever and accumulate duplicates).
|
|
const MAX_PAGES = 50;
|
|
let page = 1;
|
|
let allItems = [];
|
|
let hasNextPage = true;
|
|
while (hasNextPage && page <= MAX_PAGES) {
|
|
const response = await this.client.post(endpoint, {
|
|
...basePayload,
|
|
limit: clampedLimit,
|
|
page,
|
|
});
|
|
const data = response.data;
|
|
const items = data.data?.items || data.items || [];
|
|
const meta = data.data?.meta || data.meta;
|
|
allItems = allItems.concat(items);
|
|
// Stop if the page is empty or shorter than the requested size: a full
|
|
// page worth of items is the only situation where another page can exist,
|
|
// so this defends against a stuck hasNextPage flag in addition to it.
|
|
if (items.length === 0 || items.length < clampedLimit) {
|
|
break;
|
|
}
|
|
hasNextPage = meta?.hasNextPage || false;
|
|
page++;
|
|
}
|
|
// If the loop stopped because it hit the MAX_PAGES ceiling while the server
|
|
// still reported more results (hasNextPage true and the last page was
|
|
// full), the result set is truncated — warn so the caller is not silently
|
|
// handed an incomplete list.
|
|
if (hasNextPage && page > MAX_PAGES) {
|
|
console.warn(`paginateAll: results from "${endpoint}" truncated at the ${MAX_PAGES}-page cap; more pages exist on the server`);
|
|
}
|
|
return allItems;
|
|
}
|
|
async getWorkspace() {
|
|
await this.ensureAuthenticated();
|
|
const response = await this.client.post("/workspace/info", {});
|
|
return {
|
|
data: filterWorkspace(response.data?.data ?? response.data),
|
|
success: response.data.success,
|
|
};
|
|
}
|
|
async getSpaces() {
|
|
const spaces = await this.paginateAll("/spaces", {});
|
|
return spaces.map((space) => filterSpace(space));
|
|
}
|
|
/**
|
|
* List pages in one of two modes.
|
|
*
|
|
* Default (`tree` false): most recent pages by updatedAt (descending),
|
|
* bounded. Fetching the whole space can exceed MCP response/time limits on
|
|
* large instances, so a single bounded page of results is returned (default
|
|
* 50, max 100) via the `/pages/recent` feed.
|
|
*
|
|
* Tree (`tree` true): the space's FULL page hierarchy as a nested tree (each
|
|
* node has a `children` array). This mode REQUIRES `spaceId` (a page tree is
|
|
* scoped to one space) and IGNORES `limit` — the whole hierarchy is returned.
|
|
* It walks the sidebar tree via `enumerateSpacePages`, which performs N
|
|
* sidebar requests and is bounded by that method's 10000-node cap (and skips
|
|
* soft-deleted pages server-side).
|
|
*/
|
|
async listPages(spaceId, limit = 50, tree = false) {
|
|
await this.ensureAuthenticated();
|
|
if (tree) {
|
|
if (!spaceId) {
|
|
throw new Error("list_pages: tree mode requires a spaceId (a page tree is scoped to one space). Pass spaceId, or omit tree to get the recent-pages list.");
|
|
}
|
|
const nodes = await this.enumerateSpacePages(spaceId);
|
|
return buildPageTree(nodes);
|
|
}
|
|
const clampedLimit = Math.max(1, Math.min(100, limit));
|
|
const payload = { limit: clampedLimit, page: 1 };
|
|
if (spaceId)
|
|
payload.spaceId = spaceId;
|
|
const response = await this.client.post("/pages/recent", payload);
|
|
const data = response.data;
|
|
const items = data.data?.items || data.items || [];
|
|
return items.map((page) => filterPage(page));
|
|
}
|
|
/**
|
|
* List sidebar pages for a space. With no pageId the request returns the
|
|
* space ROOT pages; with a pageId it returns the direct CHILDREN of that
|
|
* page. pageId is therefore optional and is only included in the POST body
|
|
* when provided (an empty/undefined pageId would otherwise change the
|
|
* semantics on the server).
|
|
*/
|
|
async listSidebarPages(spaceId, pageId) {
|
|
await this.ensureAuthenticated();
|
|
// Paginate: the endpoint returns server-paged children, so posting only
|
|
// { page: 1 } silently dropped every child beyond the first page. Loop on
|
|
// meta.hasNextPage (with a MAX_PAGES ceiling like paginateAll, guarding
|
|
// against a stuck hasNextPage flag) and accumulate all children.
|
|
const MAX_PAGES = 50;
|
|
let page = 1;
|
|
let allItems = [];
|
|
let hasNextPage = true;
|
|
while (hasNextPage && page <= MAX_PAGES) {
|
|
// Only send pageId when scoping to a page's children; omit it for roots.
|
|
const payload = { spaceId, page };
|
|
if (pageId)
|
|
payload.pageId = pageId;
|
|
const response = await this.client.post("/pages/sidebar-pages", payload);
|
|
const data = response.data?.data ?? response.data;
|
|
const items = data?.items || [];
|
|
allItems = allItems.concat(items);
|
|
hasNextPage = data?.meta?.hasNextPage || false;
|
|
page++;
|
|
}
|
|
return allItems;
|
|
}
|
|
/**
|
|
* Enumerate EVERY page in a space (or in a subtree, when rootPageId is given)
|
|
* by walking the sidebar-pages tree.
|
|
*
|
|
* Starting set: the children of rootPageId when provided, otherwise the
|
|
* space root pages. From there it does an iterative breadth-first walk: each
|
|
* node is collected, and when node.hasChildren is true its direct children
|
|
* are fetched via listSidebarPages(spaceId, node.id) and enqueued.
|
|
*
|
|
* This replaces the old "/pages/recent" enumeration, which is a bounded
|
|
* recent-activity feed (~5000 cap) and therefore misses comments on older
|
|
* pages that were never recently touched.
|
|
*
|
|
* Safeguards: a `visited` Set of page ids prevents re-processing a node
|
|
* (cycles / duplicate references), and a hard node cap bounds pathological
|
|
* trees so the walk always terminates.
|
|
*/
|
|
async enumerateSpacePages(spaceId, rootPageId) {
|
|
const MAX_NODES = 10000;
|
|
const result = [];
|
|
const visited = new Set();
|
|
// Seed the queue with the starting level (subtree children or roots).
|
|
const queue = await this.listSidebarPages(spaceId, rootPageId);
|
|
while (queue.length > 0 && result.length < MAX_NODES) {
|
|
const node = queue.shift();
|
|
if (!node || typeof node !== "object" || !node.id)
|
|
continue;
|
|
// Skip already-seen ids to guard against cycles / duplicate references.
|
|
if (visited.has(node.id))
|
|
continue;
|
|
visited.add(node.id);
|
|
result.push(node);
|
|
if (node.hasChildren) {
|
|
try {
|
|
const children = await this.listSidebarPages(spaceId, node.id);
|
|
for (const child of children)
|
|
queue.push(child);
|
|
}
|
|
catch (e) {
|
|
// A failure fetching one node's children must not abort the whole
|
|
// walk: skip this branch and keep enumerating the rest.
|
|
}
|
|
}
|
|
}
|
|
return result;
|
|
}
|
|
/** Raw page info including the ProseMirror JSON content and slugId. */
|
|
async getPageRaw(pageId) {
|
|
await this.ensureAuthenticated();
|
|
const response = await this.client.post("/pages/info", { pageId });
|
|
return response.data?.data ?? response.data;
|
|
}
|
|
async getPage(pageId) {
|
|
await this.ensureAuthenticated();
|
|
const resultData = await this.getPageRaw(pageId);
|
|
let content = resultData.content
|
|
? convertProseMirrorToMarkdown(resultData.content)
|
|
: "";
|
|
// Always fetch subpages to provide context to the agent
|
|
let subpages = [];
|
|
try {
|
|
// `pageId` may be a slugId, but the sidebar-pages endpoint requires the
|
|
// UUID; `resultData.id` holds the resolved UUID returned by getPageRaw.
|
|
subpages = await this.listSidebarPages(resultData.spaceId, resultData.id);
|
|
}
|
|
catch (e) {
|
|
console.warn("Failed to fetch subpages:", e);
|
|
}
|
|
// Resolve subpages if the placeholder exists
|
|
if (content && content.includes("{{SUBPAGES}}")) {
|
|
if (subpages && subpages.length > 0) {
|
|
const list = subpages
|
|
.map((p) => `- [${p.title}](page:${p.id})`)
|
|
.join("\n");
|
|
content = content.replace("{{SUBPAGES}}", `### Subpages\n${list}`);
|
|
}
|
|
else {
|
|
content = content.replace("{{SUBPAGES}}", "");
|
|
}
|
|
}
|
|
return {
|
|
data: filterPage(resultData, content, subpages),
|
|
success: true,
|
|
};
|
|
}
|
|
/** Page info + raw ProseMirror JSON content (lossless representation). */
|
|
async getPageJson(pageId) {
|
|
const data = await this.getPageRaw(pageId);
|
|
return {
|
|
id: data.id,
|
|
slugId: data.slugId,
|
|
title: data.title,
|
|
parentPageId: data.parentPageId,
|
|
spaceId: data.spaceId,
|
|
updatedAt: data.updatedAt,
|
|
content: data.content || { type: "doc", content: [] },
|
|
};
|
|
}
|
|
/**
|
|
* Compact outline of a page's top-level blocks (no full document body).
|
|
* Cheap way to locate sections/tables and grab block ids before drilling in
|
|
* with get_node / patch_node / insert_node.
|
|
*/
|
|
async getOutline(pageId) {
|
|
await this.ensureAuthenticated();
|
|
const data = await this.getPageRaw(pageId);
|
|
return {
|
|
pageId,
|
|
slugId: data.slugId,
|
|
title: data.title,
|
|
outline: buildOutline(data.content ?? { type: "doc", content: [] }),
|
|
};
|
|
}
|
|
/**
|
|
* Fetch a single node's full ProseMirror subtree (lossless) by reference:
|
|
* a block id (headings/paragraphs/callouts/images), or `#<index>` to select
|
|
* a top-level block by its outline index (the only way to reach tables/rows/
|
|
* cells, which carry no id).
|
|
*/
|
|
async getNode(pageId, nodeId) {
|
|
await this.ensureAuthenticated();
|
|
const data = await this.getPageRaw(pageId);
|
|
const hit = getNodeByRef(data.content ?? { type: "doc", content: [] }, nodeId);
|
|
if (!hit) {
|
|
throw new Error(`get_node: no node found for "${nodeId}" on page ${pageId} (use a block id from get_outline, or "#<index>" for a top-level block such as a table)`);
|
|
}
|
|
return {
|
|
pageId,
|
|
ref: nodeId,
|
|
path: hit.path,
|
|
type: hit.type,
|
|
node: hit.node,
|
|
};
|
|
}
|
|
/**
|
|
* Read a table as a matrix. `tableRef` is `#<index>` (from get_outline) or a
|
|
* block id of any node inside the table. Returns the cell texts plus a
|
|
* parallel cellIds matrix (each cell's first paragraph id, or null) so a
|
|
* caller can patch_node a cell for rich-formatted edits. Throws when no table
|
|
* resolves for the reference.
|
|
*/
|
|
async getTable(pageId, tableRef) {
|
|
await this.ensureAuthenticated();
|
|
const data = await this.getPageRaw(pageId);
|
|
const t = readTable(data.content ?? { type: "doc", content: [] }, tableRef);
|
|
if (!t) {
|
|
throw new Error(`table_get: no table found for "${tableRef}" on page ${pageId} (use "#<index>" from get_outline, or a block id inside the table)`);
|
|
}
|
|
return {
|
|
pageId,
|
|
table: tableRef,
|
|
rows: t.rows,
|
|
cols: t.cols,
|
|
path: t.path,
|
|
cells: t.cells,
|
|
cellIds: t.cellIds,
|
|
};
|
|
}
|
|
/**
|
|
* Insert a row of plain-text cells into a table on the LIVE collab document.
|
|
* `tableRef` is `#<index>` or a block id inside the target table. `cells` is
|
|
* padded to the table's column count (more cells than columns throws); `index`
|
|
* is a 0-based insert position (omit/out-of-range to append). Throws when no
|
|
* table resolves for the reference.
|
|
*/
|
|
async tableInsertRow(pageId, tableRef, cells, index) {
|
|
await this.ensureAuthenticated();
|
|
const collabToken = await this.getCollabTokenWithReauth();
|
|
// Track insertion in an outer var, reset per-transform, so a collab retry
|
|
// recomputes it cleanly (mirrors insertNode's pattern).
|
|
let inserted = false;
|
|
const mutation = await mutatePageContent(pageId, collabToken, this.apiUrl, (liveDoc) => {
|
|
inserted = false;
|
|
const { doc: nd, inserted: ins } = insertTableRow(liveDoc, tableRef, cells, index);
|
|
inserted = ins;
|
|
if (!inserted)
|
|
return null; // table not found -> skip the write entirely
|
|
return nd;
|
|
});
|
|
if (!inserted) {
|
|
throw new Error(`table_insert_row: no table found for "${tableRef}" on page ${pageId} (use "#<index>" from get_outline, or a block id inside the table)`);
|
|
}
|
|
return {
|
|
success: true,
|
|
table: tableRef,
|
|
inserted: true,
|
|
verify: mutation.verify,
|
|
};
|
|
}
|
|
/**
|
|
* Delete the row at 0-based `index` from a table on the LIVE collab document.
|
|
* `tableRef` is `#<index>` or a block id inside the target table. The helper's
|
|
* out-of-range and last-row errors propagate; a missing table throws here.
|
|
*/
|
|
async tableDeleteRow(pageId, tableRef, index) {
|
|
await this.ensureAuthenticated();
|
|
const collabToken = await this.getCollabTokenWithReauth();
|
|
let deleted = false;
|
|
const mutation = await mutatePageContent(pageId, collabToken, this.apiUrl, (liveDoc) => {
|
|
deleted = false;
|
|
const { doc: nd, deleted: del } = deleteTableRow(liveDoc, tableRef, index);
|
|
deleted = del;
|
|
if (!deleted)
|
|
return null; // table not found -> skip the write entirely
|
|
return nd;
|
|
});
|
|
if (!deleted) {
|
|
throw new Error(`table_delete_row: no table found for "${tableRef}" on page ${pageId} (use "#<index>" from get_outline, or a block id inside the table)`);
|
|
}
|
|
return {
|
|
success: true,
|
|
table: tableRef,
|
|
deleted: true,
|
|
verify: mutation.verify,
|
|
};
|
|
}
|
|
/**
|
|
* Set the plain-text content of cell `[row, col]` (0-based) in a table on the
|
|
* LIVE collab document, replacing the cell's content with a single text
|
|
* paragraph (the cell's first-paragraph id is preserved). `tableRef` is
|
|
* `#<index>` or a block id inside the target table. The helper's out-of-range
|
|
* error propagates; a missing table throws here.
|
|
*/
|
|
async tableUpdateCell(pageId, tableRef, row, col, text) {
|
|
await this.ensureAuthenticated();
|
|
const collabToken = await this.getCollabTokenWithReauth();
|
|
let updated = false;
|
|
const mutation = await mutatePageContent(pageId, collabToken, this.apiUrl, (liveDoc) => {
|
|
updated = false;
|
|
const { doc: nd, updated: upd } = updateTableCell(liveDoc, tableRef, row, col, text);
|
|
updated = upd;
|
|
if (!updated)
|
|
return null; // table not found -> skip the write entirely
|
|
return nd;
|
|
});
|
|
if (!updated) {
|
|
throw new Error(`table_update_cell: no table found for "${tableRef}" on page ${pageId} (use "#<index>" from get_outline, or a block id inside the table)`);
|
|
}
|
|
return {
|
|
success: true,
|
|
table: tableRef,
|
|
row,
|
|
col,
|
|
verify: mutation.verify,
|
|
};
|
|
}
|
|
/**
|
|
* Create a new page with title and content.
|
|
* Uses the /pages/import workaround (the only endpoint accepting content),
|
|
* then moves the page and restores the exact title: the import endpoint
|
|
* derives the title from the FILENAME and replaces spaces with
|
|
* underscores, so we explicitly re-set it via /pages/update afterwards.
|
|
*/
|
|
async createPage(title, content, spaceId, parentPageId) {
|
|
await this.ensureAuthenticated();
|
|
if (parentPageId) {
|
|
try {
|
|
await this.getPage(parentPageId);
|
|
}
|
|
catch (e) {
|
|
throw new Error(`Parent page with ID ${parentPageId} not found.`);
|
|
}
|
|
}
|
|
// 1. Create content via Import (using multipart/form-data).
|
|
// Build a FRESH FormData per send attempt: a FormData body is a single-use
|
|
// stream consumed on the first send, so it cannot be replayed by
|
|
// this.client's response interceptor (replay fails with 'socket hang up').
|
|
// Multipart re-auth is therefore done here with bare axios and an explicit
|
|
// one-shot 401/403 retry that rebuilds the body.
|
|
const fileContent = Buffer.from(content, "utf-8");
|
|
const buildForm = () => {
|
|
const form = new FormData();
|
|
form.append("spaceId", spaceId);
|
|
form.append("file", fileContent, {
|
|
filename: `${title || "import"}.md`,
|
|
contentType: "text/markdown",
|
|
});
|
|
return form;
|
|
};
|
|
const importUrl = `${this.apiUrl}/pages/import`;
|
|
let response;
|
|
try {
|
|
// Call buildForm() ONCE per attempt and reuse the instance for both
|
|
// getHeaders() and the body so the Content-Type boundary matches the body.
|
|
const form = buildForm();
|
|
// Read the Authorization header from this.client's defaults (set by
|
|
// login(), only ever deleted — never set to null) instead of building
|
|
// `Bearer ${this.token}`: a concurrent JSON 401 can null this.token
|
|
// mid-flight, which would otherwise produce a literal "Bearer null".
|
|
// ensureAuthenticated() above guarantees login() ran, so the default
|
|
// header exists here.
|
|
response = await axios.post(importUrl, form, {
|
|
headers: {
|
|
...form.getHeaders(),
|
|
Authorization: this.client.defaults.headers.common["Authorization"],
|
|
},
|
|
timeout: 60000,
|
|
});
|
|
}
|
|
catch (error) {
|
|
// On an expired-token auth error, re-login and retry exactly once with a
|
|
// freshly-rebuilt FormData (the previous one was already consumed).
|
|
if (axios.isAxiosError(error) &&
|
|
(error.response?.status === 401 || error.response?.status === 403)) {
|
|
await this.login();
|
|
const form2 = buildForm();
|
|
response = await axios.post(importUrl, form2, {
|
|
headers: {
|
|
...form2.getHeaders(),
|
|
Authorization: this.client.defaults.headers.common["Authorization"],
|
|
},
|
|
timeout: 60000,
|
|
});
|
|
}
|
|
else {
|
|
throw error;
|
|
}
|
|
}
|
|
const newPageId = (response.data?.data ?? response.data).id;
|
|
// 2. Move to parent if needed
|
|
if (parentPageId) {
|
|
await this.movePage(newPageId, parentPageId);
|
|
}
|
|
// 3. Restore the exact title (import mangles spaces into underscores)
|
|
if (title) {
|
|
await this.client.post("/pages/update", { pageId: newPageId, title });
|
|
}
|
|
const page = await this.getPage(newPageId);
|
|
// Surface non-fatal footnote problems (dangling refs, empty/duplicate
|
|
// definitions, markers in tables) so the agent can fix its markup (#166).
|
|
return { ...page, ...footnoteWarningsField(content) };
|
|
}
|
|
/**
|
|
* Update a page's content from markdown and optionally its title.
|
|
* NOTE: full re-import — block ids regenerate. For surgical changes
|
|
* use editPageText / updatePageJson instead.
|
|
*/
|
|
async updatePage(pageId, content, title) {
|
|
await this.ensureAuthenticated();
|
|
// Write the BODY first, then the title (#159 split-brain). If the collab
|
|
// body write fails (e.g. a persist timeout), the title must be left
|
|
// UNTOUCHED so the page never ends up with a new title over its old body.
|
|
// A title write failing AFTER a successful body is rarer (REST is fast) and
|
|
// leaves correct content under a stale title — the lesser inconsistency.
|
|
let collabToken = "";
|
|
let mutation;
|
|
try {
|
|
collabToken = await this.getCollabTokenWithReauth();
|
|
mutation = await updatePageContentRealtime(pageId, content, collabToken, this.apiUrl);
|
|
}
|
|
catch (error) {
|
|
// Verbose diagnostics (incl. anything that could expose a token prefix)
|
|
// are gated behind DEBUG; the thrown Error below carries no token data.
|
|
if (process.env.DEBUG) {
|
|
console.error("Failed to update page content via realtime collaboration:", error);
|
|
const tokenPreview = collabToken
|
|
? collabToken.substring(0, 15) + "..."
|
|
: "null";
|
|
console.error(`Collab token preview: ${tokenPreview}`);
|
|
}
|
|
throw new Error(`Failed to update page content: ${error.message}`);
|
|
}
|
|
// Body persisted successfully — now it is safe to set the title.
|
|
if (title) {
|
|
await this.client.post("/pages/update", { pageId, title });
|
|
}
|
|
return {
|
|
success: true,
|
|
modified: true,
|
|
message: "Page updated successfully.",
|
|
pageId: pageId,
|
|
verify: mutation.verify,
|
|
// Non-fatal footnote diagnostics (#166); omitted when there are none.
|
|
...footnoteWarningsField(content),
|
|
};
|
|
}
|
|
/**
|
|
* Validate a URL string against a scheme allowlist for a given context.
|
|
*
|
|
* The markdown link path enforces safe schemes via TipTap, but the raw
|
|
* JSON path (updatePageJson) bypasses that — so this is the sanitization
|
|
* choke point for ProseMirror JSON written directly by the caller.
|
|
*
|
|
* - "link": reject javascript:, vbscript:, data: (any scheme that can
|
|
* execute or smuggle script when the href is clicked).
|
|
* - "src": allow only http(s):, mailto:, /api/files paths, or a
|
|
* scheme-less relative/absolute path; reject
|
|
* javascript:/vbscript:/data:/file:.
|
|
*/
|
|
isSafeUrl(url, context) {
|
|
if (typeof url !== "string")
|
|
return false;
|
|
const trimmed = url.trim();
|
|
if (trimmed === "")
|
|
return true; // empty href/src is harmless
|
|
// Extract a leading "scheme:" if present. A scheme must start with a
|
|
// letter and contain only letters/digits/+/-/. before the colon. Strip
|
|
// whitespace and ASCII control chars first so a tab/newline embedded in
|
|
// the scheme cannot smuggle a dangerous scheme past the check.
|
|
const cleaned = trimmed.replace(/[\s\x00-\x1f]+/g, "");
|
|
const schemeMatch = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(cleaned);
|
|
const scheme = schemeMatch ? schemeMatch[1].toLowerCase() : null;
|
|
const dangerous = new Set(["javascript", "vbscript", "data", "file"]);
|
|
if (context === "link") {
|
|
if (scheme === null)
|
|
return true; // relative/anchor link is fine
|
|
// For links, data: is also blocked (can carry script payloads).
|
|
return !new Set(["javascript", "vbscript", "data"]).has(scheme);
|
|
}
|
|
// context === "src"
|
|
if (scheme === null)
|
|
return true; // relative/absolute path (incl. /api/files)
|
|
if (dangerous.has(scheme))
|
|
return false;
|
|
return scheme === "http" || scheme === "https" || scheme === "mailto";
|
|
}
|
|
/**
|
|
* Recursively walk a ProseMirror doc and reject any unsafe URL on a link
|
|
* mark href or on a media node's src/url. Media nodes covered: image,
|
|
* attachment, video, plus embed (rendered as an iframe), youtube, drawio
|
|
* and excalidraw — all of which carry a user-controlled URL that Docmost
|
|
* renders. Throws a clear error on the first violation. A max-depth guard
|
|
* turns an over-deep document into a clean error instead of a RangeError
|
|
* stack overflow.
|
|
*/
|
|
validateDocUrls(node, depth = 0) {
|
|
const MAX_DEPTH = 200;
|
|
if (depth > MAX_DEPTH) {
|
|
throw new Error(`document nesting exceeds the maximum depth of ${MAX_DEPTH}`);
|
|
}
|
|
if (!node || typeof node !== "object")
|
|
return;
|
|
// Link marks on text nodes: validate the href.
|
|
if (Array.isArray(node.marks)) {
|
|
for (const mark of node.marks) {
|
|
if (mark && mark.type === "link" && mark.attrs) {
|
|
if (!this.isSafeUrl(mark.attrs.href, "link")) {
|
|
throw new Error(`unsafe link href rejected: "${mark.attrs.href}"`);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
// Media nodes: validate src/url against the stricter src allowlist.
|
|
// embed renders as an iframe (highest risk); youtube/drawio/excalidraw
|
|
// likewise carry a user-controlled URL Docmost renders, so they get the
|
|
// same scheme check as image/attachment/video.
|
|
if (node.type === "image" ||
|
|
node.type === "attachment" ||
|
|
node.type === "video" ||
|
|
node.type === "embed" ||
|
|
node.type === "youtube" ||
|
|
node.type === "drawio" ||
|
|
node.type === "excalidraw" ||
|
|
node.type === "audio" ||
|
|
node.type === "pdf") {
|
|
const attrs = node.attrs || {};
|
|
for (const key of ["src", "url"]) {
|
|
if (attrs[key] != null && !this.isSafeUrl(attrs[key], "src")) {
|
|
throw new Error(`unsafe ${node.type} ${key} rejected: "${attrs[key]}"`);
|
|
}
|
|
}
|
|
}
|
|
if (Array.isArray(node.content)) {
|
|
for (const child of node.content) {
|
|
this.validateDocUrls(child, depth + 1);
|
|
}
|
|
}
|
|
}
|
|
/**
|
|
* Recursively validate the STRUCTURE of a ProseMirror node (reuses the
|
|
* recursion shape of validateDocUrls). Every node must be an object with a
|
|
* string `type`; when present, `content` must be an array, `marks` must be
|
|
* an array of objects each with a string `type`, and a text node's `text`
|
|
* must be a string. Throws a clear "invalid ProseMirror document" error on
|
|
* the first violation. A max-depth guard turns an over-deep document into a
|
|
* clean error instead of a RangeError stack overflow.
|
|
*/
|
|
validateDocStructure(node, depth = 0) {
|
|
const MAX_DEPTH = 200;
|
|
if (depth > MAX_DEPTH) {
|
|
throw new Error(`invalid ProseMirror document: nesting exceeds the maximum depth of ${MAX_DEPTH}`);
|
|
}
|
|
if (!node || typeof node !== "object" || typeof node.type !== "string") {
|
|
throw new Error("invalid ProseMirror document: every node must be an object with a string `type`");
|
|
}
|
|
if ("text" in node &&
|
|
node.type === "text" &&
|
|
typeof node.text !== "string") {
|
|
throw new Error("invalid ProseMirror document: a text node must have a string `text`");
|
|
}
|
|
if (node.marks !== undefined) {
|
|
if (!Array.isArray(node.marks)) {
|
|
throw new Error("invalid ProseMirror document: `marks` must be an array");
|
|
}
|
|
for (const mark of node.marks) {
|
|
if (!mark ||
|
|
typeof mark !== "object" ||
|
|
typeof mark.type !== "string") {
|
|
throw new Error("invalid ProseMirror document: every mark must be an object with a string `type`");
|
|
}
|
|
}
|
|
}
|
|
if (node.content !== undefined) {
|
|
if (!Array.isArray(node.content)) {
|
|
throw new Error("invalid ProseMirror document: `content` must be an array when present");
|
|
}
|
|
for (const child of node.content) {
|
|
this.validateDocStructure(child, depth + 1);
|
|
}
|
|
}
|
|
}
|
|
/**
|
|
* Replace page content with a raw ProseMirror JSON document (lossless) and/or
|
|
* update its title. Both `doc` and `title` are optional, but at least one must
|
|
* be supplied:
|
|
* - `doc` provided -> validate + full-overwrite the body (and update the
|
|
* title too when `title` is also given).
|
|
* - `doc` omitted, `title` given -> title-only update; the body is NOT
|
|
* touched/resent (no collab write happens).
|
|
* - neither given -> throws (nothing to update).
|
|
*/
|
|
async updatePageJson(pageId, doc, title) {
|
|
await this.ensureAuthenticated();
|
|
// Title-only / no-op handling: when no document is supplied, do NOT write
|
|
// the body. Update the title if one was given; otherwise there is nothing
|
|
// to do, so fail loudly rather than silently no-op.
|
|
if (doc == null) {
|
|
if (!title) {
|
|
throw new Error("update_page_json: nothing to update (provide content and/or title)");
|
|
}
|
|
await this.client.post("/pages/update", { pageId, title });
|
|
return {
|
|
success: true,
|
|
modified: true,
|
|
message: "Page title updated (content left unchanged).",
|
|
pageId,
|
|
};
|
|
}
|
|
// Validate the document shape before a full overwrite: a malformed doc
|
|
// would otherwise silently corrupt the page (full-overwrite is the
|
|
// documented behaviour; no optimistic-concurrency is applied here).
|
|
if (typeof doc !== "object" ||
|
|
doc.type !== "doc" ||
|
|
!Array.isArray(doc.content)) {
|
|
throw new Error('content must be a ProseMirror document ({"type":"doc","content":[...]}) ' +
|
|
"where content is an array of nodes each having a string `type`");
|
|
}
|
|
// Recurse the WHOLE document so a malformed nested node (e.g. a node with a
|
|
// non-string type, a non-array content/marks, or a text node missing its
|
|
// string text) is rejected up front rather than silently corrupting the
|
|
// page on overwrite.
|
|
this.validateDocStructure(doc);
|
|
// Sanitize URLs before writing. This closes the JSON-path bypass: unlike
|
|
// the markdown link path (which TipTap sanitizes), raw JSON could otherwise
|
|
// inject javascript:/data: link hrefs or media srcs straight into the doc.
|
|
this.validateDocUrls(doc);
|
|
// Write the BODY first, then the title (#159 split-brain): a failed body
|
|
// write (e.g. persist timeout) must not leave a new title over the old body.
|
|
const collabToken = await this.getCollabTokenWithReauth();
|
|
const mutation = await replacePageContent(pageId, doc, collabToken, this.apiUrl);
|
|
// Body persisted successfully — now it is safe to set the title.
|
|
if (title) {
|
|
await this.client.post("/pages/update", { pageId, title });
|
|
}
|
|
return {
|
|
success: true,
|
|
modified: true,
|
|
message: "Page content replaced from ProseMirror JSON.",
|
|
pageId,
|
|
verify: mutation.verify,
|
|
};
|
|
}
|
|
/**
|
|
* Export a page to a single self-contained Docmost-flavoured markdown file:
|
|
* meta block + body (with inline comment anchors + diagrams) + comment
|
|
* threads. Lossless round-trip target; see importPageMarkdown for the inverse.
|
|
*/
|
|
async exportPageMarkdown(pageId) {
|
|
await this.ensureAuthenticated();
|
|
const page = await this.getPageRaw(pageId);
|
|
const body = page.content ? convertProseMirrorToMarkdown(page.content) : "";
|
|
let comments = [];
|
|
try {
|
|
comments = await this.listComments(pageId);
|
|
}
|
|
catch (e) {
|
|
// A comments fetch failure must not lose the body; export with [] and let
|
|
// the caller see the (empty) comments block. Log under DEBUG only.
|
|
if (process.env.DEBUG)
|
|
console.error("export: listComments failed", e);
|
|
}
|
|
const meta = {
|
|
version: 1,
|
|
pageId: page.id,
|
|
slugId: page.slugId,
|
|
title: page.title,
|
|
spaceId: page.spaceId,
|
|
parentPageId: page.parentPageId ?? null,
|
|
};
|
|
return serializeDocmostMarkdown(meta, body, comments);
|
|
}
|
|
/**
|
|
* Import a self-contained Docmost markdown file back into a page. Parses out
|
|
* the meta + comments metadata blocks, converts the body to ProseMirror
|
|
* (restoring comment marks + diagrams from their inline HTML), and replaces
|
|
* the page content. Comment THREAD records are NOT written to the server in
|
|
* this version — they are preserved in the file and the inline marks are
|
|
* re-applied so the highlights survive; managing comment records stays with
|
|
* the comment tools/UI.
|
|
*/
|
|
async importPageMarkdown(pageId, fullMarkdown) {
|
|
await this.ensureAuthenticated();
|
|
const { meta, body, comments } = parseDocmostMarkdown(fullMarkdown);
|
|
const doc = await markdownToProseMirror(body);
|
|
const collabToken = await this.getCollabTokenWithReauth();
|
|
const mutation = await replacePageContent(pageId, doc, collabToken, this.apiUrl);
|
|
// Collect distinct comment ids that actually became comment marks in the doc.
|
|
const collectCommentIds = (node, acc) => {
|
|
if (!node || typeof node !== "object")
|
|
return acc;
|
|
if (Array.isArray(node.marks)) {
|
|
for (const mk of node.marks) {
|
|
if (mk && mk.type === "comment" && mk.attrs?.commentId) {
|
|
acc.add(mk.attrs.commentId);
|
|
}
|
|
}
|
|
}
|
|
if (Array.isArray(node.content)) {
|
|
for (const child of node.content)
|
|
collectCommentIds(child, acc);
|
|
}
|
|
return acc;
|
|
};
|
|
// Count reflects the comment marks present in the written document, so an id
|
|
// that only appears as inert text (e.g. inside a fenced code block) is not
|
|
// counted because it never becomes a comment mark.
|
|
const anchoredIds = collectCommentIds(doc, new Set());
|
|
const result = {
|
|
success: true,
|
|
pageId,
|
|
anchoredCommentCount: anchoredIds.size,
|
|
commentsInFile: Array.isArray(comments) ? comments.length : 0,
|
|
verify: mutation.verify,
|
|
};
|
|
// Warn (non-fatal) if the file was exported from a DIFFERENT page.
|
|
if (meta?.pageId && meta.pageId !== pageId) {
|
|
result.warning = `File was exported from page ${meta.pageId} but is being imported into ${pageId}.`;
|
|
}
|
|
// Non-fatal footnote diagnostics (#166), analyzed on the BODY (the part after
|
|
// the docmost:meta / docmost:comments blocks) — so a `[^x]`-like token inside
|
|
// those JSON blocks never produces a false warning, while real markers in the
|
|
// body do. `body` comes from parseDocmostMarkdown(fullMarkdown) above.
|
|
Object.assign(result, footnoteWarningsField(body));
|
|
return result;
|
|
}
|
|
/**
|
|
* Rename a page (change its title only) without touching or resending its
|
|
* content. The slug is derived from the page record, not the body, so it is
|
|
* left intact too.
|
|
*/
|
|
async renamePage(pageId, title) {
|
|
await this.ensureAuthenticated();
|
|
await this.client.post("/pages/update", { pageId, title });
|
|
return { success: true, pageId, title };
|
|
}
|
|
/**
|
|
* Copy the WHOLE content of one page onto another, entirely server-side: the
|
|
* source's ProseMirror document is read and written verbatim onto the target
|
|
* via the live collab path, so the document never passes through the model.
|
|
*
|
|
* Only the target's BODY is replaced — its title and slug live on the page
|
|
* record (not in the content), so they are untouched. The source page is not
|
|
* modified at all.
|
|
*/
|
|
async copyPageContent(sourcePageId, targetPageId) {
|
|
await this.ensureAuthenticated();
|
|
// A self-copy would be a no-op overwrite; reject it explicitly so a caller
|
|
// mistake surfaces as a clear error rather than a silent round-trip.
|
|
if (sourcePageId === targetPageId) {
|
|
throw new Error("copy_page_content: sourcePageId and targetPageId are the same page (no-op copy)");
|
|
}
|
|
const source = await this.getPageRaw(sourcePageId);
|
|
const content = source?.content;
|
|
if (!content ||
|
|
typeof content !== "object" ||
|
|
content.type !== "doc" ||
|
|
!Array.isArray(content.content)) {
|
|
throw new Error(`copy_page_content: source page ${sourcePageId} has no usable ProseMirror content to copy`);
|
|
}
|
|
// Defense-in-depth: run the same URL-scheme sanitizer the JSON write path
|
|
// uses, so copying never lands a javascript:/data: href/src on the target
|
|
// (parity with updatePageJson; harmless for already-stored source content).
|
|
this.validateDocUrls(content);
|
|
const collabToken = await this.getCollabTokenWithReauth();
|
|
const mutation = await replacePageContent(targetPageId, content, collabToken, this.apiUrl);
|
|
return {
|
|
success: true,
|
|
sourcePageId,
|
|
targetPageId,
|
|
copiedNodes: content.content.length,
|
|
verify: mutation.verify,
|
|
};
|
|
}
|
|
/**
|
|
* Surgical text edits: find/replace inside text nodes of the live
|
|
* document. Preserves all block ids, marks, callouts and tables.
|
|
*/
|
|
async editPageText(pageId, edits) {
|
|
await this.ensureAuthenticated();
|
|
const collabToken = await this.getCollabTokenWithReauth();
|
|
// Apply the edits against the LIVE synced document, not the debounced REST
|
|
// snapshot, so concurrent human edits/comments are preserved. applyTextEdits
|
|
// records per-edit match problems in `failed` instead of throwing, and
|
|
// applies whatever it can; we abort the write only when nothing applied.
|
|
let results;
|
|
let failed;
|
|
// Whether we actually wrote new content. Set inside the transform: a
|
|
// degenerate edit (e.g. find === replace, or a batch that nets to no change)
|
|
// can "apply" yet leave the document byte-for-byte identical, in which case
|
|
// we must NOT write (no spurious history version) and must not claim a write
|
|
// happened.
|
|
let wrote = false;
|
|
const mutation = await mutatePageContent(pageId, collabToken, this.apiUrl, (liveDoc) => {
|
|
wrote = false;
|
|
const r = applyTextEdits(liveDoc, edits);
|
|
results = r.results;
|
|
failed = r.failed;
|
|
// Nothing applied -> abort the write (mutatePageContent treats a null
|
|
// return from the transform as "write nothing").
|
|
if (r.results.length === 0)
|
|
return null;
|
|
// Edits "applied" but produced an identical document: skip the write so
|
|
// no new history version is created. Stable structural comparison via
|
|
// JSON.stringify (both docs come from the same deep-copied source, so
|
|
// key order is stable).
|
|
if (JSON.stringify(r.doc) === JSON.stringify(liveDoc))
|
|
return null;
|
|
wrote = true;
|
|
return r.doc;
|
|
});
|
|
if ((results?.length ?? 0) === 0 && (failed?.length ?? 0) > 0) {
|
|
// No edit applied: surface an aggregated, actionable error so the caller
|
|
// does not mistake a no-op for a partial success.
|
|
throw new Error("edit_page_text: no edits were applied (nothing written). " +
|
|
failed.map((f) => `"${f.find}": ${f.reason}`).join("; "));
|
|
}
|
|
// Edits matched but produced no content change (identical document): report
|
|
// a successful no-op — NOT a failure — and do not falsely claim a write.
|
|
if (!wrote) {
|
|
return {
|
|
success: true,
|
|
pageId,
|
|
applied: results,
|
|
failed,
|
|
message: "No changes written (edits produced identical content).",
|
|
verify: mutation.verify,
|
|
};
|
|
}
|
|
const result = {
|
|
success: true,
|
|
pageId,
|
|
applied: results,
|
|
failed,
|
|
message: (failed?.length ?? 0)
|
|
? `Applied ${results?.length ?? 0} edit(s); ${failed.length} failed (see failed[]). Node ids and formatting preserved.`
|
|
: "Text edits applied (node ids and formatting preserved).",
|
|
verify: mutation.verify,
|
|
};
|
|
// If any applied edit matched only after stripping markdown (the
|
|
// normalized fallback), warn that edit_page_text preserved existing marks
|
|
// and did NOT change formatting — so a caller who intended a formatting
|
|
// change is pointed at patch_node.
|
|
if (results?.some((r) => r.normalized === true)) {
|
|
result.warning =
|
|
"Some edits matched only after stripping markdown from your find string; " +
|
|
"edit_page_text preserved existing marks (it did not change bold/strike/etc.). " +
|
|
"If you intended a formatting change, use patch_node.";
|
|
}
|
|
return result;
|
|
}
|
|
/**
|
|
* Replace EVERY node whose attrs.id === nodeId (recursively, including nodes
|
|
* nested in callouts/tables) with the supplied node. Operates on the LIVE
|
|
* collab document so comments and concurrent edits are preserved.
|
|
*
|
|
* The replacement node's block id is preserved: if node.attrs is missing it
|
|
* is created, and if node.attrs.id is missing it is set to nodeId so the
|
|
* replacement keeps the same id it replaced. Throws if no node matches.
|
|
*/
|
|
async patchNode(pageId, nodeId, node) {
|
|
await this.ensureAuthenticated();
|
|
if (!node || typeof node !== "object" || typeof node.type !== "string") {
|
|
throw new Error("patch_node: `node` must be an object with a string `type`");
|
|
}
|
|
// Preserve the block id WITHOUT mutating the caller's object: build a local
|
|
// copy whose attrs.id === nodeId (so the swapped-in node keeps the id of the
|
|
// node it replaces).
|
|
const target = {
|
|
...node,
|
|
attrs: {
|
|
...(node.attrs && typeof node.attrs === "object" ? node.attrs : {}),
|
|
},
|
|
};
|
|
if (target.attrs.id == null) {
|
|
target.attrs.id = nodeId;
|
|
}
|
|
const collabToken = await this.getCollabTokenWithReauth();
|
|
// Track the replacement count in an outer var, reset per-transform, so a
|
|
// collab retry recomputes it cleanly (mirrors replaceImage's pattern).
|
|
let replaced = 0;
|
|
const mutation = await mutatePageContent(pageId, collabToken, this.apiUrl, (liveDoc) => {
|
|
replaced = 0;
|
|
const { doc: nd, replaced: r } = replaceNodeById(liveDoc, nodeId, target);
|
|
replaced = r;
|
|
// 0 matches -> skip the write. >1 matches -> the id is AMBIGUOUS: Docmost
|
|
// duplicates block ids on copy/paste (and copyPageContent writes them
|
|
// verbatim), so replacing "the node with id X" would silently clobber
|
|
// EVERY duplicate (#159). Refuse: skip the write and throw below so the
|
|
// model re-targets with a more specific anchor instead of corrupting the
|
|
// page. Only an unambiguous single match is written.
|
|
if (replaced !== 1)
|
|
return null;
|
|
return nd;
|
|
});
|
|
// 0 -> "no node"; >1 -> "ambiguous, refused" (the transform already skipped
|
|
// the write for any count !== 1). Single shared guard (#159, #185 review).
|
|
assertUnambiguousMatch("patch_node", "replace", replaced, nodeId, pageId);
|
|
return { success: true, replaced, nodeId, verify: mutation.verify };
|
|
}
|
|
/**
|
|
* Insert a node relative to an anchor (or append it at the top level).
|
|
* Operates on the LIVE collab document so comments and concurrent edits are
|
|
* preserved.
|
|
*
|
|
* opts.position:
|
|
* - "append": push the node at the end of the top-level content.
|
|
* - "before"/"after": insert the node as a sibling of the anchor, just
|
|
* before/after it. Exactly one of anchorNodeId / anchorText must be given;
|
|
* anchorNodeId locates a node anywhere by attrs.id, anchorText matches the
|
|
* first top-level block whose plain text includes it.
|
|
*
|
|
* Throws if the anchor cannot be found.
|
|
*/
|
|
async insertNode(pageId, node, opts) {
|
|
await this.ensureAuthenticated();
|
|
if (!node || typeof node !== "object" || typeof node.type !== "string") {
|
|
throw new Error("insert_node: `node` must be an object with a string `type`");
|
|
}
|
|
if (!opts ||
|
|
(opts.position !== "before" &&
|
|
opts.position !== "after" &&
|
|
opts.position !== "append")) {
|
|
throw new Error('insert_node: `position` must be one of "before", "after", "append"');
|
|
}
|
|
if (opts.position === "before" || opts.position === "after") {
|
|
// before/after require EXACTLY ONE anchor (an id or a text fragment).
|
|
const hasId = typeof opts.anchorNodeId === "string" && opts.anchorNodeId.length > 0;
|
|
const hasText = typeof opts.anchorText === "string" && opts.anchorText.length > 0;
|
|
if (hasId === hasText) {
|
|
throw new Error(`insert_node: position "${opts.position}" requires exactly one of anchorNodeId or anchorText`);
|
|
}
|
|
}
|
|
const collabToken = await this.getCollabTokenWithReauth();
|
|
// Track insertion in an outer var, reset per-transform, so a collab retry
|
|
// recomputes it cleanly (mirrors replaceImage's pattern).
|
|
let inserted = false;
|
|
const mutation = await mutatePageContent(pageId, collabToken, this.apiUrl, (liveDoc) => {
|
|
inserted = false;
|
|
const { doc: nd, inserted: ins } = insertNodeRelative(liveDoc, node, opts);
|
|
inserted = ins;
|
|
if (!inserted)
|
|
return null; // anchor not found -> skip the write entirely
|
|
return nd;
|
|
});
|
|
if (!inserted) {
|
|
const anchorDesc = opts.anchorNodeId
|
|
? `anchorNodeId "${opts.anchorNodeId}"`
|
|
: `anchorText "${opts.anchorText}"`;
|
|
// anchorText is matched against the block's literal RENDERED plain text;
|
|
// markdown/emoji are tolerated only as a strip-and-retry fallback, so a
|
|
// miss usually means the text differs from what's on the page.
|
|
const hint = opts.anchorText
|
|
? " anchorText must be the block's literal rendered plain text (no markdown wrappers or emoji); anchorNodeId from get_page_json is more reliable."
|
|
: "";
|
|
throw new Error(`insert_node: anchor not found (${anchorDesc}) on page ${pageId}.${hint}`);
|
|
}
|
|
return {
|
|
success: true,
|
|
inserted: true,
|
|
position: opts.position,
|
|
verify: mutation.verify,
|
|
};
|
|
}
|
|
/**
|
|
* Remove EVERY node whose attrs.id === nodeId (recursively, including nodes
|
|
* nested in callouts/tables) from its parent content array. Operates on the
|
|
* LIVE collab document so comments and concurrent edits are preserved.
|
|
* Throws if no node matches.
|
|
*/
|
|
async deleteNode(pageId, nodeId) {
|
|
await this.ensureAuthenticated();
|
|
const collabToken = await this.getCollabTokenWithReauth();
|
|
// Track the deletion count in an outer var, reset per-transform, so a
|
|
// collab retry recomputes it cleanly (mirrors replaceImage's pattern).
|
|
let deleted = 0;
|
|
const mutation = await mutatePageContent(pageId, collabToken, this.apiUrl, (liveDoc) => {
|
|
deleted = 0;
|
|
const { doc: nd, deleted: d } = deleteNodeById(liveDoc, nodeId);
|
|
deleted = d;
|
|
// 0 matches -> skip the write. >1 matches -> the id is AMBIGUOUS (block
|
|
// ids are duplicated on copy/paste, #159): deleting "the node with id X"
|
|
// would silently remove EVERY duplicate. Refuse: skip the write and throw
|
|
// below so the model re-targets. Only an unambiguous single match is
|
|
// deleted.
|
|
if (deleted !== 1)
|
|
return null;
|
|
return nd;
|
|
});
|
|
// 0 -> "no node"; >1 -> "ambiguous, refused" (the transform already skipped
|
|
// the write for any count !== 1). Single shared guard (#159, #185 review).
|
|
assertUnambiguousMatch("delete_node", "delete", deleted, nodeId, pageId);
|
|
return { success: true, deleted, nodeId, verify: mutation.verify };
|
|
}
|
|
/** Build the public share URL for a page. */
|
|
shareUrl(shareKey, slugId) {
|
|
return `${this.appUrl}/share/${shareKey}/p/${slugId}`;
|
|
}
|
|
/** Share a page publicly (idempotent) and return the public URL. */
|
|
async sharePage(pageId, searchIndexing = true) {
|
|
await this.ensureAuthenticated();
|
|
const response = await this.client.post("/shares/create", {
|
|
pageId,
|
|
includeSubPages: false,
|
|
searchIndexing,
|
|
});
|
|
const share = response.data?.data ?? response.data;
|
|
const slugId = share.page?.slugId || (await this.getPageRaw(pageId)).slugId;
|
|
return {
|
|
shareId: share.id,
|
|
key: share.key,
|
|
pageId: share.pageId,
|
|
publicUrl: this.shareUrl(share.key, slugId),
|
|
searchIndexing: share.searchIndexing,
|
|
};
|
|
}
|
|
/** List all public shares in the workspace with their URLs. */
|
|
async listShares() {
|
|
const shares = await this.paginateAll("/shares", {});
|
|
return shares.map((s) => ({
|
|
shareId: s.id,
|
|
key: s.key,
|
|
pageId: s.pageId,
|
|
pageTitle: s.page?.title,
|
|
publicUrl: s.page?.slugId ? this.shareUrl(s.key, s.page.slugId) : null,
|
|
searchIndexing: s.searchIndexing,
|
|
createdAt: s.createdAt,
|
|
}));
|
|
}
|
|
/** Remove the public share of a page. */
|
|
async unsharePage(pageId) {
|
|
await this.ensureAuthenticated();
|
|
const shares = await this.listShares();
|
|
const share = shares.find((s) => s.pageId === pageId);
|
|
if (!share) {
|
|
throw new Error(`Page ${pageId} is not shared.`);
|
|
}
|
|
await this.client.post("/shares/delete", { shareId: share.shareId });
|
|
return { success: true, removedShareId: share.shareId, pageId };
|
|
}
|
|
async search(query, spaceId, limit) {
|
|
await this.ensureAuthenticated();
|
|
const payload = { query, spaceId };
|
|
// Clamp an optional caller-supplied limit into a sane 1..100 range before
|
|
// forwarding it to the server; omit it entirely when not provided so the
|
|
// server applies its own default.
|
|
if (limit !== undefined) {
|
|
payload.limit = Math.max(1, Math.min(100, limit));
|
|
}
|
|
const response = await this.client.post("/search", payload);
|
|
// Normalize both response shapes: bare array and paginated { items: [...] }
|
|
const data = response.data?.data;
|
|
const items = Array.isArray(data) ? data : data?.items || [];
|
|
const filteredItems = items.map((item) => filterSearchResult(item));
|
|
return {
|
|
items: filteredItems,
|
|
success: response.data?.success || false,
|
|
};
|
|
}
|
|
async movePage(pageId, parentPageId, position) {
|
|
await this.ensureAuthenticated();
|
|
// Docmost requires position >= 5 chars.
|
|
const validPosition = position || "a00000";
|
|
return this.client
|
|
.post("/pages/move", {
|
|
pageId,
|
|
parentPageId,
|
|
position: validPosition,
|
|
})
|
|
.then((res) => res.data);
|
|
}
|
|
async deletePage(pageId) {
|
|
await this.ensureAuthenticated();
|
|
return this.client
|
|
.post("/pages/delete", { pageId })
|
|
.then((res) => res.data);
|
|
}
|
|
// --- Comment methods (ported from upstream PR #3 by Max Nikitin) ---
|
|
/**
|
|
* Normalize a comment's `content` into a ProseMirror doc object before
|
|
* markdown conversion. createComment/updateComment send content as a
|
|
* JSON.stringify(...) STRING, and the server stores it as-is, so on read it
|
|
* comes back as a string. convertProseMirrorToMarkdown returns "" for a
|
|
* string, so parse it first (guarded — fall back to the raw value on any
|
|
* parse failure so a non-JSON legacy value is still handled gracefully).
|
|
*/
|
|
parseCommentContent(content) {
|
|
if (typeof content !== "string")
|
|
return content;
|
|
try {
|
|
return JSON.parse(content);
|
|
}
|
|
catch {
|
|
return content;
|
|
}
|
|
}
|
|
/** List all comments on a page (cursor-paginated), content as markdown. */
|
|
async listComments(pageId) {
|
|
await this.ensureAuthenticated();
|
|
let allComments = [];
|
|
let cursor = null;
|
|
do {
|
|
const payload = { pageId, limit: 100 };
|
|
if (cursor)
|
|
payload.cursor = cursor;
|
|
const response = await this.client.post("/comments", payload);
|
|
const data = response.data.data || response.data;
|
|
const items = data.items || [];
|
|
allComments = allComments.concat(items);
|
|
cursor = data.meta?.nextCursor || null;
|
|
} while (cursor);
|
|
return allComments.map((comment) => {
|
|
const markdown = comment.content
|
|
? convertProseMirrorToMarkdown(this.parseCommentContent(comment.content))
|
|
: "";
|
|
return filterComment(comment, markdown);
|
|
});
|
|
}
|
|
async getComment(commentId) {
|
|
await this.ensureAuthenticated();
|
|
const response = await this.client.post("/comments/info", { commentId });
|
|
const comment = response.data.data || response.data;
|
|
const markdown = comment.content
|
|
? convertProseMirrorToMarkdown(this.parseCommentContent(comment.content))
|
|
: "";
|
|
return {
|
|
data: filterComment(comment, markdown),
|
|
success: true,
|
|
};
|
|
}
|
|
/**
|
|
* Create an inline comment anchored to its `selection` text, or a reply.
|
|
*
|
|
* Top-level comments (no `parentCommentId`) are ALWAYS inline and MUST carry a
|
|
* `selection`: the `type` argument is kept for interface compatibility but the
|
|
* effective type is coerced to "inline". The selection has to anchor in the
|
|
* document; if it cannot, the comment is rolled back and an error is thrown so
|
|
* the caller is forced to supply a proper inline selection rather than leaving
|
|
* an orphan, unanchored comment behind. Replies (parentCommentId set) inherit
|
|
* their parent's anchor: they take NO selection and are not anchored.
|
|
*/
|
|
async createComment(pageId, content, type = "page", selection, parentCommentId) {
|
|
await this.ensureAuthenticated();
|
|
const isReply = !!parentCommentId;
|
|
// Only top-level comments are inline-anchored, so they are stored as
|
|
// "inline". Replies carry no inline selection, so they keep the historical
|
|
// general ("page") type — both backward-compatible and semantically correct.
|
|
// The `type` argument is kept for interface compatibility; createComment
|
|
// normalizes the effective type internally, so callers may pass "inline".
|
|
const effectiveType = isReply ? "page" : "inline";
|
|
if (!isReply && (!selection || !selection.trim())) {
|
|
throw new Error("create_comment: an inline 'selection' (exact text to anchor on) is required for a top-level comment");
|
|
}
|
|
// For a top-level comment, fail BEFORE creating anything when the selection
|
|
// is not present in the persisted document — this avoids leaving an orphan
|
|
// comment + notification behind. A read failure (network) is non-fatal: the
|
|
// live anchor step below still enforces the anchoring invariant.
|
|
if (!isReply && selection) {
|
|
try {
|
|
const page = await this.getPageJson(pageId);
|
|
if (!canAnchorInDoc(page.content, selection)) {
|
|
throw new Error("create_comment: could not find the selection text in the page to anchor the comment. " +
|
|
"Provide the EXACT contiguous text from a single paragraph/block (<=250 chars).");
|
|
}
|
|
}
|
|
catch (e) {
|
|
// Rethrow our own "not found" error; swallow read/network errors so the
|
|
// live anchor step can still try (and enforce) the anchoring.
|
|
if (e instanceof Error &&
|
|
e.message.startsWith("create_comment: could not find the selection")) {
|
|
throw e;
|
|
}
|
|
if (process.env.DEBUG) {
|
|
console.error("Pre-check getPageJson failed; deferring to live anchor step:", e);
|
|
}
|
|
}
|
|
}
|
|
// Convert through the full Docmost schema (consistent with page paths)
|
|
const jsonContent = await markdownToProseMirror(content);
|
|
const payload = {
|
|
pageId,
|
|
content: JSON.stringify(jsonContent),
|
|
type: effectiveType,
|
|
};
|
|
if (!isReply && selection)
|
|
payload.selection = selection;
|
|
if (parentCommentId)
|
|
payload.parentCommentId = parentCommentId;
|
|
const response = await this.client.post("/comments/create", payload);
|
|
const comment = response.data.data || response.data;
|
|
const markdown = comment.content
|
|
? convertProseMirrorToMarkdown(this.parseCommentContent(comment.content))
|
|
: content;
|
|
const result = {
|
|
data: filterComment(comment, markdown),
|
|
success: true,
|
|
};
|
|
// Replies inherit the parent's anchor: no selection, no anchoring.
|
|
if (isReply) {
|
|
return result;
|
|
}
|
|
// Anchor the comment in the document. The /comments/create API records the
|
|
// comment + its `selection` text, but it does NOT insert the comment MARK
|
|
// into the page content, so without this the inline comment has no
|
|
// highlight/anchor and is not clickable. If anchoring fails the comment is
|
|
// rolled back (deleted) and an error is thrown — never an orphan comment.
|
|
const newCommentId = comment.id;
|
|
// Guard: a create response without an id would mean writing a comment mark
|
|
// with commentId: undefined and a later delete of a falsy id. We have no id
|
|
// to roll back here (nothing was created with an id), so just fail loudly.
|
|
if (!newCommentId) {
|
|
throw new Error("create_comment: the server returned no comment id, so the comment could not be anchored");
|
|
}
|
|
let anchored = false;
|
|
try {
|
|
const collabToken = await this.getCollabTokenWithReauth();
|
|
const mutation = await mutatePageContent(pageId, collabToken, this.apiUrl, (liveDoc) => {
|
|
const doc = liveDoc && liveDoc.type === "doc"
|
|
? liveDoc
|
|
: { type: "doc", content: [] };
|
|
if (applyAnchorInDoc(doc, selection, newCommentId)) {
|
|
anchored = true;
|
|
return doc;
|
|
}
|
|
// Selection text not found in the LIVE document: abort the write. The
|
|
// rollback + throw below turns this into a hard error.
|
|
return null;
|
|
});
|
|
result.verify = mutation.verify;
|
|
}
|
|
catch (e) {
|
|
// The comment record already exists; roll it back so we never leave an
|
|
// orphan, then rethrow the original anchoring error.
|
|
await this.safeDeleteComment(newCommentId);
|
|
throw e;
|
|
}
|
|
if (!anchored) {
|
|
// Mutation aborted because the selection was not found in the live
|
|
// document. Roll back the comment and surface a hard error.
|
|
await this.safeDeleteComment(newCommentId);
|
|
throw new Error("create_comment: failed to anchor the comment (selection not found in the live document); the comment was rolled back");
|
|
}
|
|
result.anchored = true;
|
|
return result;
|
|
}
|
|
/**
|
|
* Best-effort rollback of a just-created comment. Swallows any delete failure
|
|
* (logging under DEBUG) so a failed cleanup never masks the original error.
|
|
*/
|
|
async safeDeleteComment(commentId) {
|
|
// Defense in depth: never call the delete API with a falsy id — there is
|
|
// nothing to roll back, and deleteComment(undefined) would hit a bad route.
|
|
if (!commentId)
|
|
return;
|
|
try {
|
|
await this.deleteComment(commentId);
|
|
}
|
|
catch (delErr) {
|
|
if (process.env.DEBUG) {
|
|
console.error("Failed to roll back comment after anchoring error:", delErr);
|
|
}
|
|
}
|
|
}
|
|
async updateComment(commentId, content) {
|
|
await this.ensureAuthenticated();
|
|
const jsonContent = await markdownToProseMirror(content);
|
|
await this.client.post("/comments/update", {
|
|
commentId,
|
|
content: JSON.stringify(jsonContent),
|
|
});
|
|
return {
|
|
success: true,
|
|
commentId,
|
|
message: "Comment updated successfully.",
|
|
};
|
|
}
|
|
async deleteComment(commentId) {
|
|
await this.ensureAuthenticated();
|
|
return this.client
|
|
.post("/comments/delete", { commentId })
|
|
.then((res) => res.data);
|
|
}
|
|
/**
|
|
* Resolve or reopen a top-level comment thread (reversible — `resolved`
|
|
* toggles the state). Only top-level comments can be resolved; the server
|
|
* rejects resolving a reply. Hits POST /comments/resolve.
|
|
*/
|
|
async resolveComment(commentId, resolved) {
|
|
await this.ensureAuthenticated();
|
|
const response = await this.client.post("/comments/resolve", {
|
|
commentId,
|
|
resolved,
|
|
});
|
|
const comment = response.data?.data ?? response.data;
|
|
return {
|
|
success: true,
|
|
commentId,
|
|
resolved,
|
|
comment,
|
|
};
|
|
}
|
|
/**
|
|
* Check for new comments across pages in a space (optionally scoped to a
|
|
* subtree): pages updated after `since` are scanned and their comments
|
|
* filtered by createdAt > since.
|
|
*/
|
|
async checkNewComments(spaceId, since, parentPageId) {
|
|
await this.ensureAuthenticated();
|
|
const sinceDate = new Date(since);
|
|
// Reject an unparseable `since`: comparing against an Invalid Date silently
|
|
// yields zero new comments (every `>` against NaN is false), which would
|
|
// mask a malformed input as "nothing new" instead of erroring.
|
|
if (Number.isNaN(sinceDate.getTime())) {
|
|
throw new Error(`checkNewComments: invalid "since" date "${since}"; expected an ISO-8601 timestamp`);
|
|
}
|
|
// 1. Enumerate the FULL set of pages in scope by walking the sidebar-pages
|
|
// tree (a complete page index), NOT the bounded "/pages/recent" feed which
|
|
// caps at ~5000 recent items and silently misses comments on older pages.
|
|
//
|
|
// Subtree scope: when parentPageId is given, the scope is that page ITSELF
|
|
// plus every descendant (enumerateSpacePages walks its children). Otherwise
|
|
// the scope is the whole space (all roots and their descendants).
|
|
//
|
|
// NOTE: do NOT pre-filter by page.updatedAt — creating a comment does not
|
|
// bump it (verified on a live server), so such a filter silently misses
|
|
// comments on pages that were not otherwise edited. The complete tree walk
|
|
// already restricts the scope correctly, so no recent-feed allow-list is
|
|
// needed any more.
|
|
let pagesInScope;
|
|
if (parentPageId) {
|
|
const subtree = await this.enumerateSpacePages(spaceId, parentPageId);
|
|
// Include the parent page node itself alongside its descendants. Fetch it
|
|
// so its title/id are available even though it is not returned by its own
|
|
// children listing.
|
|
let parentNode = { id: parentPageId };
|
|
try {
|
|
parentNode = await this.getPageRaw(parentPageId);
|
|
}
|
|
catch (e) {
|
|
// Fall back to a minimal node if the parent can't be fetched; its
|
|
// comments are still attempted below (the fetch there is non-fatal).
|
|
}
|
|
pagesInScope = [parentNode, ...subtree];
|
|
}
|
|
else {
|
|
pagesInScope = await this.enumerateSpacePages(spaceId);
|
|
}
|
|
// 2. Fetch comments for each page, keep ones created after since
|
|
const results = [];
|
|
for (const page of pagesInScope) {
|
|
try {
|
|
const comments = await this.listComments(page.id);
|
|
const newComments = comments.filter((c) => new Date(c.createdAt) > sinceDate);
|
|
if (newComments.length > 0) {
|
|
results.push({
|
|
pageId: page.id,
|
|
pageTitle: page.title,
|
|
comments: newComments,
|
|
});
|
|
}
|
|
}
|
|
catch (e) {
|
|
// Skip pages with errors (e.g. deleted between calls)
|
|
}
|
|
}
|
|
const totalNewComments = results.reduce((sum, r) => sum + r.comments.length, 0);
|
|
// enumerateSpacePages caps traversal at 10000 nodes; flag when that cap was
|
|
// hit so the caller knows the scan may be incomplete (some pages skipped).
|
|
const truncated = pagesInScope.length >= 10000;
|
|
return {
|
|
since,
|
|
scope: parentPageId ? `subtree of ${parentPageId}` : `space ${spaceId}`,
|
|
checkedPages: pagesInScope.length,
|
|
pagesWithNewComments: results.length,
|
|
totalNewComments,
|
|
truncated,
|
|
comments: results,
|
|
};
|
|
}
|
|
// --- Image upload / embedding ---
|
|
/** Map a Content-Type string to a supported MIME type, or null if unsupported. */
|
|
supportedImageMime(ct) {
|
|
return MIME_TO_EXT[ct] ? ct : null;
|
|
}
|
|
/**
|
|
* Download a remote image from a caller-supplied URL and resolve its bytes,
|
|
* MIME and a filename.
|
|
*
|
|
* SSRF / RESOURCE TRUST BOUNDARY: the URL comes from the MCP caller and is
|
|
* fetched BY THE SERVER, so it must be guarded before and after the request.
|
|
* The guards mirror the local-file trust boundary in uploadImage:
|
|
* - scheme allowlist (http/https only) — rejects file:, data:, ftp:, etc.,
|
|
* so the caller cannot use this path to read local files or other schemes;
|
|
* - a size cap enforced both via axios maxContentLength/maxBodyLength AND a
|
|
* post-download buffer.length re-check (defends against a missing/lying
|
|
* Content-Length), so a huge response cannot exhaust memory;
|
|
* - a 30s timeout. The timeout matters because replaceImage holds the
|
|
* per-page lock across this upload, so a hung download would wedge the
|
|
* lock for that page.
|
|
* We deliberately do NOT block private IP ranges: the MCP caller is already
|
|
* trusted to read arbitrary host files via the filePath path, so the marginal
|
|
* trust granted by fetching internal URLs is comparable, and blocking would
|
|
* break legitimate internal-image use.
|
|
*/
|
|
async fetchRemoteImage(url, maxBytes) {
|
|
// Scheme allowlist first — cheapest guard, and rejects non-http(s) schemes
|
|
// (file:, data:, ftp:, ...) before any network request is made.
|
|
let parsed;
|
|
try {
|
|
parsed = new URL(url);
|
|
}
|
|
catch (e) {
|
|
throw new Error(`Invalid image URL "${url}": ${e.message}`);
|
|
}
|
|
if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
|
|
throw new Error(`unsupported image URL scheme "${parsed.protocol}"; only http and https are allowed`);
|
|
}
|
|
let response;
|
|
try {
|
|
response = await axios.get(url, {
|
|
responseType: "arraybuffer",
|
|
timeout: 30000,
|
|
maxContentLength: maxBytes,
|
|
maxBodyLength: maxBytes,
|
|
headers: { Accept: "image/*" },
|
|
});
|
|
}
|
|
catch (error) {
|
|
// Keep the thrown message free of the raw response body (it may echo
|
|
// server internals); surface only status/statusText. The full body is
|
|
// logged under DEBUG for diagnostics.
|
|
if (axios.isAxiosError(error)) {
|
|
if (process.env.DEBUG) {
|
|
console.error("Image download failed; response body:", JSON.stringify(error.response?.data));
|
|
}
|
|
throw new Error(`Image download failed for "${url}": ${error.response?.status ?? ""} ${error.response?.statusText ?? error.message}`.trim());
|
|
}
|
|
throw error;
|
|
}
|
|
// axios returns an ArrayBuffer for responseType: "arraybuffer".
|
|
const buffer = Buffer.from(response.data);
|
|
// Re-check the size: maxContentLength relies on Content-Length, which may be
|
|
// absent or lie, so guard against the actual byte count too.
|
|
if (buffer.length === 0) {
|
|
throw new Error(`Empty image response from "${url}"`);
|
|
}
|
|
if (buffer.length > maxBytes) {
|
|
throw new Error(`Image too large: ${buffer.length} bytes exceeds the ${maxBytes}-byte cap`);
|
|
}
|
|
// Resolve MIME: prefer the response Content-Type (strip any "; charset=..."
|
|
// parameter, lowercase, trim) mapped through the supported set; if the
|
|
// header is generic/missing/unsupported, fall back to the URL path
|
|
// extension via the existing extension->MIME logic.
|
|
const rawCt = response.headers?.["content-type"];
|
|
let mime = null;
|
|
if (typeof rawCt === "string" && rawCt.length > 0) {
|
|
const ct = rawCt.split(";")[0].trim().toLowerCase();
|
|
mime = this.supportedImageMime(ct);
|
|
}
|
|
if (!mime) {
|
|
// Fall back to the URL path extension. Use the pathname so the query
|
|
// string never contaminates the extension lookup.
|
|
const ext = extname(parsed.pathname).toLowerCase();
|
|
mime = EXT_TO_MIME[ext] ?? null;
|
|
}
|
|
if (!mime) {
|
|
throw new Error(`cannot determine supported image type for "${url}"; supported: png, jpg, jpeg, gif, webp, svg`);
|
|
}
|
|
// Build a filename from the URL path basename (ignore the query string),
|
|
// defaulting to "image" when empty, and ensure it ends with the canonical
|
|
// extension for the resolved MIME (append it when missing/mismatched).
|
|
const canonicalExt = MIME_TO_EXT[mime];
|
|
let fileName = basename(parsed.pathname) || "image";
|
|
if (extname(fileName).toLowerCase() !== canonicalExt) {
|
|
fileName += canonicalExt;
|
|
}
|
|
return { buffer, mime, fileName };
|
|
}
|
|
/** Build a Docmost ProseMirror image node from an uploaded attachment. */
|
|
buildImageNode(att, align, alt) {
|
|
// Clean file URL, matching Docmost's native behaviour. No cache-busting
|
|
// query: the server serves the bare URL correctly, and replacement creates
|
|
// a new attachment id (a new URL) which busts caches naturally.
|
|
const src = `/api/files/${att.id}/${att.fileName}`;
|
|
const node = {
|
|
type: "image",
|
|
attrs: {
|
|
src,
|
|
attachmentId: att.id,
|
|
// Default to null when the server omits fileSize so the attr is never
|
|
// undefined (undefined would be dropped on serialization / break the
|
|
// ProseMirror image schema which expects size present).
|
|
size: att.fileSize ?? null,
|
|
align: align || "center",
|
|
width: null,
|
|
},
|
|
};
|
|
if (alt)
|
|
node.attrs.alt = alt;
|
|
return node;
|
|
}
|
|
/**
|
|
* Download a remote image from an http(s) URL and upload it as an attachment
|
|
* of a page, returning the attachment metadata plus a ready-to-insert
|
|
* ProseMirror image node. Local file paths are intentionally not supported:
|
|
* the MCP caller is a remote AI with no access to this server's filesystem.
|
|
*/
|
|
async uploadImage(pageId, url) {
|
|
await this.ensureAuthenticated();
|
|
const MAX_IMAGE_BYTES = 20 * 1024 * 1024; // 20 MiB
|
|
// Fetch + validate the remote image (scheme allowlist, size cap, timeout).
|
|
// See fetchRemoteImage for the SSRF / resource trust boundary.
|
|
const fetched = await this.fetchRemoteImage(url, MAX_IMAGE_BYTES);
|
|
const fileBuffer = fetched.buffer;
|
|
const mime = fetched.mime;
|
|
const fileName = fetched.fileName;
|
|
// Build a FRESH FormData for every send attempt. A FormData body is a
|
|
// single-use stream that is CONSUMED on the first send, so it cannot be
|
|
// replayed by this.client's response interceptor (replaying a consumed
|
|
// stream fails with 'socket hang up'). Multipart re-auth is therefore done
|
|
// here with bare axios and an explicit one-shot 401/403 retry that rebuilds
|
|
// the body. Field order matters: text fields must precede the file part so
|
|
// the server reads them; the server always generates a fresh attachment id.
|
|
const buildForm = () => {
|
|
const form = new FormData();
|
|
form.append("pageId", pageId);
|
|
form.append("file", fileBuffer, {
|
|
filename: fileName,
|
|
contentType: mime,
|
|
});
|
|
return form;
|
|
};
|
|
// Local name distinct from the `url` parameter (the source image URL): this
|
|
// is the /files/upload endpoint we POST the multipart body to.
|
|
const uploadUrl = `${this.apiUrl}/files/upload`;
|
|
let response;
|
|
try {
|
|
// Call buildForm() ONCE per attempt and reuse the instance for both
|
|
// getHeaders() and the body so the Content-Type boundary matches the body.
|
|
const form = buildForm();
|
|
// Read the Authorization header from this.client's defaults (set by
|
|
// login(), only ever deleted — never set to null) instead of building
|
|
// `Bearer ${this.token}`: a concurrent JSON 401 can null this.token
|
|
// mid-flight, which would otherwise produce a literal "Bearer null".
|
|
// ensureAuthenticated() above guarantees login() ran, so the default
|
|
// header exists here. A 60s timeout keeps a hung upload from wedging the
|
|
// per-page lock (replaceImage holds withPageLock across this call).
|
|
response = await axios.post(uploadUrl, form, {
|
|
headers: {
|
|
...form.getHeaders(),
|
|
Authorization: this.client.defaults.headers.common["Authorization"],
|
|
},
|
|
timeout: 60000,
|
|
});
|
|
}
|
|
catch (error) {
|
|
// On an expired-token auth error, re-login and retry exactly once with a
|
|
// freshly-rebuilt FormData (the previous one was already consumed).
|
|
if (axios.isAxiosError(error) &&
|
|
(error.response?.status === 401 || error.response?.status === 403)) {
|
|
await this.login();
|
|
const form2 = buildForm();
|
|
response = await axios.post(uploadUrl, form2, {
|
|
headers: {
|
|
...form2.getHeaders(),
|
|
Authorization: this.client.defaults.headers.common["Authorization"],
|
|
},
|
|
timeout: 60000,
|
|
});
|
|
}
|
|
else if (axios.isAxiosError(error)) {
|
|
// Keep the thrown message free of the raw response body (it may echo
|
|
// request data or server internals); surface only status/statusText.
|
|
// The full body is logged under DEBUG for diagnostics.
|
|
if (process.env.DEBUG) {
|
|
console.error("Image upload failed; response body:", JSON.stringify(error.response?.data));
|
|
}
|
|
throw new Error(`Image upload failed: ${error.response?.status} ${error.response?.statusText}`);
|
|
}
|
|
else {
|
|
throw error;
|
|
}
|
|
}
|
|
// The attachment may arrive bare or wrapped in a { data } envelope.
|
|
const att = response.data?.data ?? response.data;
|
|
if (!att?.id || !att?.fileName) {
|
|
throw new Error("Unexpected /files/upload response: " + JSON.stringify(response.data));
|
|
}
|
|
// Some Docmost versions omit fileSize from the upload response. Fall back
|
|
// to the fetched byte length (the bytes we just uploaded) so callers never
|
|
// get an undefined size.
|
|
const resolvedSize = att.fileSize ?? fileBuffer.length;
|
|
return {
|
|
attachmentId: att.id,
|
|
fileName: att.fileName,
|
|
fileSize: resolvedSize,
|
|
src: `/api/files/${att.id}/${att.fileName}`,
|
|
imageNode: this.buildImageNode({ ...att, fileSize: resolvedSize }),
|
|
};
|
|
}
|
|
/**
|
|
* Upload an image from a web (http/https) URL and insert it into a page in
|
|
* one step.
|
|
* By default the image is appended at the end. With replaceText, the first
|
|
* top-level block whose text contains the string is replaced; with afterText,
|
|
* the image is inserted right after the first matching block. All other
|
|
* block ids are preserved (only one top-level block is added or swapped).
|
|
*/
|
|
async insertImage(pageId, url, opts = {}) {
|
|
const up = await this.uploadImage(pageId, url);
|
|
// Reuse the node from uploadImage (clean /api/files/<id>/<file> src), then
|
|
// apply align/alt onto a shallow attrs copy.
|
|
const node = { ...up.imageNode, attrs: { ...up.imageNode.attrs } };
|
|
if (opts.align)
|
|
node.attrs.align = opts.align;
|
|
if (opts.alt)
|
|
node.attrs.alt = opts.alt;
|
|
const collabToken = await this.getCollabTokenWithReauth();
|
|
// Recursively collect the plain text of a top-level block.
|
|
const blockText = (n) => {
|
|
let out = "";
|
|
if (n.type === "text")
|
|
out += n.text || "";
|
|
for (const child of n.content || [])
|
|
out += blockText(child);
|
|
return out;
|
|
};
|
|
// Insert into the LIVE synced document, not the debounced REST snapshot, so
|
|
// concurrent edits/comments/images are preserved and parallel insert_image
|
|
// calls (serialized by the per-page lock) each see the previous insertion.
|
|
let placement;
|
|
const mutation = await mutatePageContent(pageId, collabToken, this.apiUrl, (liveDoc) => {
|
|
const doc = liveDoc && liveDoc.type === "doc"
|
|
? liveDoc
|
|
: { type: "doc", content: [] };
|
|
if (!Array.isArray(doc.content))
|
|
doc.content = [];
|
|
if (opts.replaceText) {
|
|
// Ambiguity guard (mirrors editPageText): count matching top-level
|
|
// blocks first, so a non-unique fragment cannot silently replace the
|
|
// wrong block (e.g. text that also appears inside a callout/table).
|
|
const matches = doc.content.filter((b) => blockText(b).includes(opts.replaceText));
|
|
if (matches.length === 0) {
|
|
throw new Error(`replaceText not found: "${opts.replaceText}"`);
|
|
}
|
|
if (matches.length > 1) {
|
|
throw new Error(`replaceText "${opts.replaceText}" matches ${matches.length} blocks; use a longer unique fragment`);
|
|
}
|
|
const idx = doc.content.findIndex((b) => blockText(b).includes(opts.replaceText));
|
|
// Data-loss guard: replaceText swaps the WHOLE top-level block, so if
|
|
// the fragment only appears nested inside a container (table, callout,
|
|
// list, blockquote) the entire structure would be destroyed. Refuse
|
|
// when the matched block is a container rather than a leaf
|
|
// paragraph/heading and point the caller at a safer tool.
|
|
const CONTAINER_TYPES = new Set([
|
|
"table",
|
|
"callout",
|
|
"bulletList",
|
|
"orderedList",
|
|
"taskList",
|
|
"blockquote",
|
|
]);
|
|
const matchedBlock = doc.content[idx];
|
|
if (matchedBlock && CONTAINER_TYPES.has(matchedBlock.type)) {
|
|
throw new Error(`replaceText matched a ${matchedBlock.type} container block; replacing it would destroy the whole structure. ` +
|
|
`Use afterText to insert near it, or update_page_json for surgical edits.`);
|
|
}
|
|
doc.content.splice(idx, 1, node);
|
|
placement = "replaced";
|
|
}
|
|
else if (opts.afterText) {
|
|
// Ambiguity guard (mirrors editPageText): refuse a non-unique fragment.
|
|
const matches = doc.content.filter((b) => blockText(b).includes(opts.afterText));
|
|
if (matches.length === 0) {
|
|
throw new Error(`afterText not found: "${opts.afterText}"`);
|
|
}
|
|
if (matches.length > 1) {
|
|
throw new Error(`afterText "${opts.afterText}" matches ${matches.length} blocks; use a longer unique fragment`);
|
|
}
|
|
const idx = doc.content.findIndex((b) => blockText(b).includes(opts.afterText));
|
|
doc.content.splice(idx + 1, 0, node);
|
|
placement = "after";
|
|
}
|
|
else {
|
|
doc.content.push(node);
|
|
placement = "appended";
|
|
}
|
|
return doc;
|
|
});
|
|
return {
|
|
success: true,
|
|
pageId,
|
|
attachmentId: up.attachmentId,
|
|
src: up.src,
|
|
placement,
|
|
verify: mutation.verify,
|
|
};
|
|
}
|
|
/**
|
|
* Replace an existing image in a page with a new image fetched from a web
|
|
* (http/https) URL. Uploads the new file as a brand-new attachment, which
|
|
* yields a fresh clean URL that both renders correctly and busts browser
|
|
* caches (the URL changed). Finds every image node
|
|
* whose attrs.attachmentId === oldAttachmentId (recursively, incl. nodes nested
|
|
* in callouts/tables) and repoints its src/attachmentId/size, preserving
|
|
* comments, alignment and alt. Operates on the live collab document so comments
|
|
* and concurrent edits are preserved. Throws if no matching image is found.
|
|
*
|
|
* The OLD attachment is left in place as an unreferenced orphan: Docmost
|
|
* exposes NO HTTP API to delete a single content attachment (verified against
|
|
* the attachment controller/service and by probing the live API — deletion
|
|
* happens only by cascade when the page, space or user is removed). This is the
|
|
* same outcome as Docmost's own editor when an image is removed/replaced.
|
|
* In-place byte overwrite is deliberately NOT used because some Docmost
|
|
* versions corrupt the attachment (HTTP 500) when its bytes are overwritten.
|
|
*/
|
|
async replaceImage(pageId, oldAttachmentId, url, opts = {}) {
|
|
const collabToken = await this.getCollabTokenWithReauth();
|
|
// Hold ONE per-page lock for the WHOLE operation (scan -> upload -> write).
|
|
// Previously the scan and the write were two separate mutatePageContent
|
|
// calls, each acquiring + releasing the lock, with the upload happening in
|
|
// the UNLOCKED gap between them. A concurrent op could interleave there: it
|
|
// could remove the target image so the write pass matches nothing, leaving
|
|
// the freshly-uploaded attachment as an un-deletable orphan (Docmost has no
|
|
// API to delete a single content attachment). Acquiring the lock once and
|
|
// using the non-locking collab helper inside (the per-page mutex is NOT
|
|
// reentrant, so the self-locking mutatePageContent would deadlock here)
|
|
// closes that TOCTOU window. uploadImage hits /files/upload over plain HTTP
|
|
// and does not touch the page lock, so it is safe to call while held.
|
|
return withPageLock(pageId, async () => {
|
|
// STEP 1: read-only live check. Scan the live document for any image node
|
|
// matching oldAttachmentId BEFORE uploading anything, so a wrong/stale id
|
|
// throws without ever creating an orphan attachment.
|
|
let matchFound = false;
|
|
const scan = (nodes) => {
|
|
for (const node of nodes) {
|
|
if (!node)
|
|
continue;
|
|
if (node.type === "image" &&
|
|
node.attrs &&
|
|
node.attrs.attachmentId === oldAttachmentId) {
|
|
matchFound = true;
|
|
}
|
|
if (Array.isArray(node.content))
|
|
scan(node.content);
|
|
}
|
|
};
|
|
await this.mutateLiveContentUnlocked(pageId, collabToken, (liveDoc) => {
|
|
matchFound = false; // reset per-transform (collab may retry the read).
|
|
const doc = liveDoc && liveDoc.type === "doc"
|
|
? liveDoc
|
|
: { type: "doc", content: [] };
|
|
if (Array.isArray(doc.content))
|
|
scan(doc.content);
|
|
return null; // read-only: never write on the check pass.
|
|
});
|
|
if (!matchFound) {
|
|
throw new Error(`replace_image: no image with attachmentId "${oldAttachmentId}" found on page ${pageId}`);
|
|
}
|
|
// STEP 2: a match exists — upload the new file as a FRESH attachment (new
|
|
// id, new clean URL) and repoint every matching node in a second pass.
|
|
// Still inside the SAME lock, so no other op can have changed the page
|
|
// since the scan.
|
|
const up = await this.uploadImage(pageId, url);
|
|
let replaced = 0;
|
|
// Swap the source of one image node, preserving align/alt/title/geometry.
|
|
const repoint = (node) => {
|
|
node.attrs = {
|
|
...node.attrs,
|
|
src: up.src,
|
|
attachmentId: up.attachmentId,
|
|
// Default to null when fileSize is unknown so the attr is never
|
|
// undefined.
|
|
size: up.fileSize ?? null,
|
|
};
|
|
if (opts.align)
|
|
node.attrs.align = opts.align;
|
|
if (opts.alt !== undefined)
|
|
node.attrs.alt = opts.alt;
|
|
replaced++;
|
|
};
|
|
// Recursively repoint every image node (incl. ones nested in callouts/tables).
|
|
const walk = (nodes) => {
|
|
for (const node of nodes) {
|
|
if (!node)
|
|
continue;
|
|
if (node.type === "image" &&
|
|
node.attrs &&
|
|
node.attrs.attachmentId === oldAttachmentId) {
|
|
repoint(node);
|
|
}
|
|
if (Array.isArray(node.content))
|
|
walk(node.content);
|
|
}
|
|
};
|
|
const mutation = await this.mutateLiveContentUnlocked(pageId, collabToken, (liveDoc) => {
|
|
// Reset per-transform so collab retries recompute cleanly (no double-count).
|
|
replaced = 0;
|
|
const doc = liveDoc && liveDoc.type === "doc"
|
|
? liveDoc
|
|
: { type: "doc", content: [] };
|
|
if (!Array.isArray(doc.content))
|
|
doc.content = [];
|
|
walk(doc.content);
|
|
if (replaced === 0)
|
|
return null; // no match -> skip the write entirely
|
|
return doc;
|
|
});
|
|
// KNOWN LIMITATION: a same-count image SRC swap (image count unchanged, no
|
|
// text/mark change) may still report verify.changed === false, because the
|
|
// text+marks+integrity-count model in summarizeChange does not inspect
|
|
// image `src`/attachmentId attributes. That is acceptable here — the
|
|
// replace is confirmed by `replaced` below, and verify is supplementary.
|
|
if (replaced === 0) {
|
|
// The pass-1 SCAN found the target (matchFound was true) and we already
|
|
// uploaded the new attachment, but pass-2 matched nothing — a concurrent
|
|
// editor must have removed the node between the two passes. Do NOT throw
|
|
// here (that would leak the just-uploaded attachment AND report failure);
|
|
// instead report success with the upload flagged as an unreferenced
|
|
// orphan so the caller knows. (The early throw above still covers the
|
|
// case where pass-1 finds nothing, before any upload happens.)
|
|
return {
|
|
success: true,
|
|
replaced: 0,
|
|
pageId,
|
|
oldAttachmentId,
|
|
newAttachmentId: up.attachmentId,
|
|
src: up.src,
|
|
orphanedAttachmentId: up.attachmentId,
|
|
warning: "target image was removed concurrently; uploaded attachment is unreferenced",
|
|
verify: mutation.verify,
|
|
};
|
|
}
|
|
return {
|
|
success: true,
|
|
pageId,
|
|
replaced,
|
|
oldAttachmentId,
|
|
newAttachmentId: up.attachmentId,
|
|
src: up.src,
|
|
verify: mutation.verify,
|
|
};
|
|
});
|
|
}
|
|
// --- Page history / diff / transform ---
|
|
/**
|
|
* List the saved versions (history snapshots) of a page, newest first.
|
|
* Docmost auto-snapshots on every save. Returns one cursor-paginated page of
|
|
* results: `{ items, nextCursor }`. The history record's id field is `id`.
|
|
*/
|
|
async listPageHistory(pageId, cursor) {
|
|
await this.ensureAuthenticated();
|
|
const payload = { pageId };
|
|
if (cursor)
|
|
payload.cursor = cursor;
|
|
const response = await this.client.post("/pages/history", payload);
|
|
const data = response.data?.data ?? response.data;
|
|
return {
|
|
items: data?.items ?? [],
|
|
nextCursor: data?.meta?.nextCursor ?? null,
|
|
};
|
|
}
|
|
/**
|
|
* Fetch a single page-history version including its lossless ProseMirror
|
|
* `content`. The version also carries pageId/title/createdAt.
|
|
*/
|
|
async getPageHistory(historyId) {
|
|
await this.ensureAuthenticated();
|
|
const response = await this.client.post("/pages/history/info", {
|
|
historyId,
|
|
});
|
|
return response.data?.data ?? response.data;
|
|
}
|
|
/**
|
|
* "Restore" a version: Docmost has NO restore endpoint, so we take the
|
|
* version's `content` and write it as the page's current content via the live
|
|
* collab path (which itself creates a new history snapshot). Returns the
|
|
* affected pageId and the source historyId.
|
|
*/
|
|
async restorePageVersion(historyId) {
|
|
await this.ensureAuthenticated();
|
|
const version = await this.getPageHistory(historyId);
|
|
if (!version ||
|
|
!version.pageId ||
|
|
!version.content ||
|
|
typeof version.content !== "object") {
|
|
throw new Error(`restore_page_version: history ${historyId} has no usable content`);
|
|
}
|
|
// Defense-in-depth: sanitize URLs in the restored content (parity with the
|
|
// JSON write path) before writing it back.
|
|
this.validateDocUrls(version.content);
|
|
const collabToken = await this.getCollabTokenWithReauth();
|
|
const mutation = await mutatePageContent(version.pageId, collabToken, this.apiUrl, () => version.content);
|
|
return {
|
|
pageId: version.pageId,
|
|
restoredFrom: historyId,
|
|
verify: mutation.verify,
|
|
};
|
|
}
|
|
/**
|
|
* Diff two versions of a page and return a Docmost-equivalent change set.
|
|
* `from`/`to` each resolve to a ProseMirror doc:
|
|
* - null / undefined / "current" -> the page's CURRENT content;
|
|
* - any other string -> that historyId's content.
|
|
* Returns the diff plus the resolved version metadata for each side.
|
|
*/
|
|
async diffPageVersions(pageId, from, to) {
|
|
await this.ensureAuthenticated();
|
|
const isCurrent = (v) => v == null || v === "" || v === "current";
|
|
const resolveSide = async (v) => {
|
|
if (isCurrent(v)) {
|
|
const raw = await this.getPageRaw(pageId);
|
|
return {
|
|
doc: raw.content || { type: "doc", content: [] },
|
|
meta: {
|
|
kind: "current",
|
|
pageId,
|
|
title: raw.title,
|
|
updatedAt: raw.updatedAt,
|
|
},
|
|
};
|
|
}
|
|
const version = await this.getPageHistory(v);
|
|
return {
|
|
doc: version.content || { type: "doc", content: [] },
|
|
meta: {
|
|
kind: "history",
|
|
historyId: version.id,
|
|
pageId: version.pageId,
|
|
title: version.title,
|
|
createdAt: version.createdAt,
|
|
},
|
|
};
|
|
};
|
|
const fromSide = await resolveSide(from);
|
|
const toSide = await resolveSide(to);
|
|
const diff = diffDocs(fromSide.doc, toSide.doc);
|
|
return { from: fromSide.meta, to: toSide.meta, diff };
|
|
}
|
|
/**
|
|
* Edit a page by running an arbitrary user-supplied JS transform against the
|
|
* live document, with a diff preview + page-history safety net.
|
|
*
|
|
* The transform string is evaluated as `(doc, ctx) => doc` inside a node:vm
|
|
* sandbox: it gets ONLY `{ doc, ctx, structuredClone, console }` as globals,
|
|
* a 5s timeout, and NO access to require/process/fs/network. It must return a
|
|
* `{ type: "doc" }` node, which is validated structurally before any write.
|
|
*
|
|
* `ctx` exposes:
|
|
* - comments: the page's comments (fetched before the live read);
|
|
* - log: an array the transform can push diagnostics to (via console.log);
|
|
* - consume(id): mark a comment id as consumed (for deleteComments);
|
|
* - helpers: the transforms.ts primitives + commentsToFootnotes.
|
|
*
|
|
* Footnote convention used by the helpers: footnote markers are plain "[N]"
|
|
* text in the body, and the notes are an orderedList under a heading whose
|
|
* text is "Примечания переводчика".
|
|
*
|
|
* dryRun (default true): read the page's current content, run the transform,
|
|
* and return `{ pushed:false, diff, log }` WITHOUT opening the collab socket.
|
|
* Otherwise the transform runs atomically inside mutatePageContent, optionally
|
|
* deletes consumed comments, and returns the new historyId + diff + log.
|
|
*/
|
|
async transformPage(pageId, transformJs, opts = {}) {
|
|
const dryRun = opts.dryRun ?? true;
|
|
const deleteComments = opts.deleteComments ?? false;
|
|
await this.ensureAuthenticated();
|
|
const comments = await this.listComments(pageId);
|
|
// ctx handed to the sandbox. consume() records ids; helpers are the pure
|
|
// transform primitives. log is captured from console.log inside the sandbox.
|
|
const ctx = {
|
|
comments,
|
|
log: [],
|
|
consumed: new Set(),
|
|
consume(id) {
|
|
this.consumed.add(id);
|
|
},
|
|
helpers: {
|
|
blockText,
|
|
walk,
|
|
getList,
|
|
insertMarkerAfter,
|
|
setCalloutRange,
|
|
noteItem,
|
|
mdToInlineNodes,
|
|
commentsToFootnotes,
|
|
},
|
|
};
|
|
// Captured oldDoc / newDoc for the diff (set inside runTransform).
|
|
let oldDoc;
|
|
let newDoc;
|
|
// SYNCHRONOUS transform runner — safe to call inside mutatePageContent's
|
|
// onSynced (no await between the live read and the write).
|
|
const runTransform = (liveDoc) => {
|
|
oldDoc = structuredClone(liveDoc);
|
|
const sandbox = {
|
|
doc: structuredClone(liveDoc),
|
|
ctx,
|
|
structuredClone,
|
|
console: {
|
|
log: (...a) => ctx.log.push(a.map((x) => String(x)).join(" ")),
|
|
},
|
|
};
|
|
// Wrap the provided string in parentheses so both an expression-arrow
|
|
// (`(doc, ctx) => {...}`) and a parenthesized function work. Run it in a
|
|
// fresh context with no require/process/module so the transform cannot
|
|
// touch fs/network/process. 5s wall-clock timeout.
|
|
let fn;
|
|
try {
|
|
fn = vm.runInNewContext("(" + transformJs + ")", sandbox, {
|
|
timeout: 5000,
|
|
});
|
|
}
|
|
catch (e) {
|
|
throw new Error(`transform did not compile: ${e?.message ?? e}`);
|
|
}
|
|
if (typeof fn !== "function") {
|
|
throw new Error("transform must evaluate to a function (doc, ctx) => doc");
|
|
}
|
|
const result = vm.runInNewContext("f(d, c)", { f: fn, d: sandbox.doc, c: ctx }, { timeout: 5000 });
|
|
if (!result ||
|
|
typeof result !== "object" ||
|
|
result.type !== "doc" ||
|
|
!Array.isArray(result.content)) {
|
|
throw new Error('transform must return a ProseMirror doc node ({ type:"doc", content:[...] })');
|
|
}
|
|
// Validate the returned doc before it can be written.
|
|
this.validateDocStructure(result);
|
|
this.validateDocUrls(result);
|
|
newDoc = result;
|
|
return result;
|
|
};
|
|
if (dryRun) {
|
|
// Preview only: run against the current REST snapshot, never open the
|
|
// socket. oldDoc/newDoc are captured by runTransform.
|
|
const raw = await this.getPageRaw(pageId);
|
|
const current = raw.content || { type: "doc", content: [] };
|
|
runTransform(current);
|
|
// Run an independent Yjs-encodability check (same sanitize + schema as the
|
|
// apply path), so the preview fails with the same descriptive error when
|
|
// the doc is not encodable instead of returning a misleadingly-green diff.
|
|
assertYjsEncodable(newDoc);
|
|
return {
|
|
pushed: false,
|
|
diff: diffDocs(oldDoc, newDoc),
|
|
log: ctx.log,
|
|
};
|
|
}
|
|
// Apply atomically against the live doc.
|
|
const collabToken = await this.getCollabTokenWithReauth();
|
|
const mutation = await mutatePageContent(pageId, collabToken, this.apiUrl, runTransform);
|
|
// Optionally delete consumed comments (best-effort; a delete failure must
|
|
// not undo the successful write).
|
|
const deletedComments = [];
|
|
if (deleteComments) {
|
|
for (const id of ctx.consumed) {
|
|
try {
|
|
await this.deleteComment(id);
|
|
deletedComments.push(id);
|
|
}
|
|
catch (e) {
|
|
if (process.env.DEBUG) {
|
|
console.error(`transform: failed to delete comment ${id}:`, e);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
// Fetch the newest historyId (Docmost snapshots on the write above).
|
|
let historyId = null;
|
|
try {
|
|
const hist = await this.listPageHistory(pageId);
|
|
historyId = hist.items?.[0]?.id ?? null;
|
|
}
|
|
catch (e) {
|
|
if (process.env.DEBUG) {
|
|
console.error("transform: failed to fetch history id:", e);
|
|
}
|
|
}
|
|
return {
|
|
pushed: true,
|
|
historyId,
|
|
diff: diffDocs(oldDoc, newDoc),
|
|
deletedComments,
|
|
log: ctx.log,
|
|
verify: mutation.verify,
|
|
};
|
|
}
|
|
}
|