@reviseio/sdk/backend is the server half of the same package: Revise’s
converters and document-local semantic tools running under plain Node, against
a Y.Doc your process owns. No React, no browser, no model required — and no
separate service of ours in the path. It is what lets your server participate
in the same collaborative documents your users have open in the browser.
yjs (one copy, shared with everything else that touches
the document) and jsdom (the converters parse XML and HTML with DOM APIs).
The entry point is ESM-only and ships fully typed declarations, including for
moduleResolution: "NodeNext".
Everything heavy loads lazily: a host that only converts files never pays for
the editor’s mutation engine, and the first call installs the DOM shims for
you.
Conversion
The same converters the editor runs in the browser, so a document produced here is identical to one a client would have built.Promise<ReviseDocument>
Parse
.docx, .md, .txt, or .html into Revise’s document model. The
format is read from the filename. ReviseDocument is deliberately opaque —
convert it rather than inspecting it.Promise<Uint8Array>
Serialize the document model back to
.docx bytes, comments and tracked
changes included.Rooms: create, seed, persist, export
The Yjs-document primitives that make a server the owner of document lifecycle rather than a bystander. See collaboration for the workflows these compose into.Y.Doc
A
Y.Doc built with the settings the editor requires. Start here when the
server creates the room.Promise<Y.Doc>
Parse a file and return a fresh
Y.Doc holding it — server-side document
creation in one call.Promise<boolean>
Seed an empty shared document from a file and report whether anything
was written. A room that already holds a document is left alone, so this is
safe to call on every connection.
Uint8Array
The whole room as one opaque update, for storage or shipping.
Y.Doc
Restore a room from stored bytes.
boolean
Whether a
Y.Doc already holds a Revise document.ReviseDocument
Read a room back as the document model.
Promise<Uint8Array>
Export a room straight to
.docx — a download endpoint or an archive job,
with no browser involved. Pending tracked changes export as native Word
revisions.Throws if a document already uses the editor’s reserved top-level keys
(
RESERVED_DOCUMENT_KEYS) for something else — the check the editor itself
runs before joining.Promise<void>
Install the DOM globals the converters need. Every function here calls it
for you; exported for hosts importing converters directly.
The document session
Promise<ServerDocumentSession>
Bind Revise’s canonical semantic tools to a host-owned
Y.Doc. Async
because the tool session loads the editor’s mutation engine on first use —
conversion-only hosts never pay for it.Mode
"suggesting" | "editing"
The mode subsequent mutations will capture.
void
Switch the posture for subsequent calls. A per-call
{ directMode: boolean } option overrides in either direction.Tools
The session’stools object speaks the shared tool
contract — the same envelope, the same typed
inputs, and the same error class as editor.tools in the browser.
ReviseToolDefinition[]
The document-local tool catalogue: 24 of the browser’s 26 tools, minus
get_selection and view_image. Schemas and descriptions carry no
document_id — a session is bound to one document. See the
tool reference.Promise<ReviseToolResult<Name>>
Typed execution; expected failures come back as
{ ok: false, error }.Promise<ReviseToolResult<string>>
Untrusted model-provided names and JSON. A supplied
document_id is
rejected with a structured failure.Promise<ReviseToolResponse<Name>>
Application-code form: returns the successful response and throws a typed
ReviseToolError when the tool rejects the call.suggestionIds — the tracked records that call
created (empty for direct edits, null for read/search/measure tools).
Persist them with your review workflow; they are the handle for accept and
reject later, on either surface.
Suggestion review
The same per-ID decision surface the browser’sreview controller exposes.
ReviseSuggestionRecord[]
Every pending tracked suggestion in the
Y.Doc as a reviewable record with
authorship metadata (authorType, agentName, agentModel, source,
label, createdAt) — including collaborators’ suggestions in a shared
document. Filter by author before bulk decisions.string[]
The bare ID list underneath
listSuggestions().ReviseSuggestionDecision
Settle specific suggestions by ID — the primary review path. The result is
per-ID:
resolved settled now, missing were not pending (a later edit to
the same block can supersede earlier records), unresolved could not be
settled.ReviseSuggestionDecision
Whole-document decisions, collaborators’ pending suggestions included.
Prefer the ID-targeted path unless the host owns the entire document.
Lifecycle
void
Release Revise’s observers and request/search state. The host-owned
Y.Doc
deliberately remains alive. Safe to call twice; every other member throws
once disposed.Errors
class extends Error
Thrown by
tools.call() on both surfaces for expected tool rejections.
Carries tool, code, callId, and the full failure object. Expected
failures through execute()/executeDynamic() arrive as
{ ok: false, error } results instead.Shared contract types
The tool contract —ReviseToolResult, ReviseToolResponse,
ReviseToolFailure, ReviseSuggestionDecision, ReviseSuggestionRecord,
the generated ReviseToolInputMap, and friends — is exported by
@reviseio/sdk and @reviseio/sdk/backend alike, so host result-handling
code is shared verbatim between web and Node. The shapes are listed in
types.
Node-only types: ServerDocumentSession, ServerDocumentSessionOptions,
ServerDocumentMode, ReviseServerFormat ("docx" | "markdown" | "txt" | "html" — the formats readable on the server; PDF and images are
browser-only).