The book

this.app.project reads the open book and, with project:write, changes it. Every method returns a promise. Items are known by their ids, which nodes(), manuscript() and selected() give you.

const p = this.app.project
for (const id of await p.manuscript()) {             // the scenes, in reading order
  const text = await p.readText(id)                  // or read(id) for its HTML
  const meta = await p.meta(id)                      // synopsis, notes, keywords, fields, when, words
  if (meta && text.length > 20_000) await p.setMeta(id, { keywords: [...meta.keywords, 'long'] })
}

What it reads: info(), nodes(), node(id), manuscript(), selected(), read, readText, meta, labels(), statuses(), comments(id), snapshots(id), collections(), search(query, { wholeWord, caseSensitive, regex }), which works as Find in project does, and series().

What it changes, with project:write:

Text: write(id, html).
The binder: create(type, title, parentId?), rename, move(id, folderId, index?), and trash, which moves an item to the trash, never further.
Cards and comments: setMeta(id, patch) (synopsis, notes, keywords, fields, when), setLabel, setStatus (by id; '' for none), and resolveComment.
Collections: createCollection(name, ids) and addToCollection.

Some things are always safe:

Snapshots: before a plugin first rewrites a document, Bläck Studio keeps a snapshot of it under the plugin's name. snapshot(id, label) keeps one yourself, without any permission.
Undo: every change is saved, can be undone, and is committed like the writer's own.
Settings → Plugins lists what each plugin changed lately.
Ids: a method given an item's id throws if the book has no such item, so an id never stands for anything but one of the book's own.

getData() and setData(value) keep data of the plugin's own in the book, saved with it. Data that belongs to the plugin rather than a book goes in loadData and saveData.

To know when the binder changes (an item made, renamed, moved or trashed), listen for nodes-change: this.on('nodes-change', () => …).

#The book

The book