API reference

Create a new character. Requires at least name.

addCharacter(data: CharacterInput) → Promise<Character>

Create a new document in the project. Returns the created doc metadata.

addDoc(data: DocInput) → Promise<DocMetadata>

Create a new file in the project. Returns the created file metadata.

addFile(data: FileInput) → Promise<FileMetadata>

Save an image (a base64 string or a data: URI) into the project and return a reference to the saved image. Assign it to a character/worldbuilding portrait or landscape. Requires the project.write.images scope. Pairs with net.fetch({ responseType: 'base64' }) to import a remote image.

addImage(data: string, fileName?: string) → Promise<string>

Create a new note. Requires location.

addNote(data: NoteInput) → Promise<Note>

Create a new worldbuilding element. Requires name and type.

addWorldbuildingElement(data: WorldbuildingInput) → Promise<WorldbuildingElement>

Get all cardboard grids with their cells.

getCardboards() → Promise<CardboardGrid[]>

Get a character by ID.

getCharacterById(id: string) → Promise<Character | null>

Get all characters.

getCharacters() → Promise<Character[]>

Get all collections.

getCollections() → Promise<Collection[]>

Get the project's custom worldbuilding templates. Read-only.

getCustomWorldbuildingTemplates() → Promise<CustomWorldbuildingTemplate[]>

Get the raw content of a document by its ID. Returns a ProseMirror/TipTap JSON string, or null. Same format as getFileContent().

getDocContent(docId: string) → Promise<string | null>

Get all documents (metadata only).

getDocs() → Promise<DocMetadata[]>

Get the raw content of a file by its ID. Returns the file content as a ProseMirror/TipTap JSON string (the internal document format), or null if the file does not exist or has no content. You must JSON.parse() the result to obtain a ProseMirrorDocument object, or pass the raw string directly to tintero.convert.toHtml() / toMarkdown() / toText(). Those methods accept both the raw string and a parsed object.

getFileContent(fileId: string) → Promise<string | null>

Get the version snapshots of a file by its ID. Read-only.

getFileSnapshots(fileId: string) → Promise<FileSnapshot[]>

Get all project files (metadata only, no content).

getFiles() → Promise<FileMetadata[]>

Get all flow maps (nodes and connections). Read-only.

getFlowMaps() → Promise<FlowMap[]>

Get the project's folder tree structure.

getFolders() → Promise<FolderInfo[]>

Get a project image as a base64 data URL. Accepts the image fileName or relativePath (e.g. "portrait.png" or "images/portrait.png"). Returns a string like "data:image/png;base64,..." or null if not found. Use this to display project images inside plugin iframes.

getImageData(imageRef: string) → Promise<string | null>

Get all images metadata.

getImages() → Promise<ImageInfo[]>

Get project metadata (name, dates, description).

getMetadata() → Promise<ProjectMetadata>

Get all notes.

getNotes() → Promise<Note[]>

Get all plot grids with their columns and cells.

getPlotGrids() → Promise<PlotGrid[]>

Get the scenes defined within a file by its ID. Read-only.

getScenes(fileId: string) → Promise<Scene[]>

Get all project tags.

getTags() → Promise<string[]>

Get all timelines (lanes, blocks, notes, milestones). Read-only.

getTimelines() → Promise<Timeline[]>

Get the per-day word count log. Read-only.

getWordCountLog() → Promise<WordCountLog[]>

Get all worldbuilding elements.

getWorldbuilding() → Promise<WorldbuildingElement[]>

Get worldbuilding elements by type (e.g. "location", "faction").

getWorldbuildingByType(type: string) → Promise<WorldbuildingElement[]>

Get the user's writing goals (words/chapters/minutes targets). Read-only.

getWritingGoals() → Promise<WritingGoal[]>

Get the per-day writing-minutes log. Read-only.

getWritingMinutesLog() → Promise<WritingMinutesLog[]>

Delete a worldbuilding element by ID.

removeWorldbuildingElement(id: string) → Promise<void>

Update an existing character's fields. Only provided fields are changed.

updateCharacter(id: string, data: Partial<CharacterInput>) → Promise<void>

Update the content of a document. Same format as updateFileContent().

updateDocContent(docId: string, jsonContent: string) → Promise<void>

Update document metadata (not content). Only provided fields are changed.

updateDocMeta(id: string, data: DocMetaUpdate) → Promise<void>

Update the content of a file. jsonContent must be a ProseMirror/TipTap JSON string, i.e. the result of JSON.stringify(proseMirrorDocumentObject). To build a document from other formats, use tintero.convert.fromHtml(), fromMarkdown(), or fromText() first, then JSON.stringify() the returned object before passing it here.

updateFileContent(fileId: string, jsonContent: string) → Promise<void>

Update file metadata (not content). Only provided fields are changed.

updateFileMeta(id: string, data: FileMetaUpdate) → Promise<void>

Replace all project tags.

updateTags(tags: string[]) → Promise<void>

Update an existing worldbuilding element.

updateWorldbuildingElement(id: string, data: Partial<WorldbuildingInput>) → Promise<void>

Delete a file from the project directory (relative path).

deleteProjectFile(location: string) → Promise<void>

Get the current platform as a compound string: "<os> | <runtime>". Examples: "darwin | Desktop", "win32 | Desktop", "linux | Desktop", "ios | Mobile", "android | Mobile", "unknown | Web".

getPlatform() → Promise<string>

Read a file from the project directory (relative path).

readProjectFile(location: string) → Promise<string | null>

Save the project metadata to disk.

saveProject() → Promise<void>

Write a file to the project directory (relative path).

writeProjectFile(location: string, content: string) → Promise<void>

Close the plugin's open dialog.

closeDialog() → Promise<void>

Hide the application sidebar.

hideSidebar() → Promise<void>

Check if the application is currently in fullscreen mode.

isFullscreen() → Promise<boolean>

Open a modal dialog for this plugin.

openDialog(options?: DialogOptions) → Promise<void>

Render HTML into the active context. If a dialog is open for this plugin, renders into the dialog. Otherwise, renders into the sidebar panel's #plugin-root.

render(html: string) → Promise<void>

Show a toast notification.

showNotification(message: string, type?: NotificationType, durationMs?: number) → Promise<void>

Show the application sidebar.

showSidebar() → Promise<void>

Toggle fullscreen mode (Desktop only).

toggleFullscreen() → Promise<void>

Toggle the application sidebar visibility.

toggleSidebar() → Promise<void>

Get a stored value by key. Returns null if not found.

get(key: string) → Promise<any | null>

Get all stored key-value pairs.

getAll() → Promise<Record<string, any>>

Remove a stored key.

remove(key: string) → Promise<void>

Store a value. Values are JSON-serializable.

set(key: string, value: any) → Promise<void>

Get all plugin settings (manifest defaults merged with stored overrides).

get() → Promise<Record<string, any>>

Get a specific setting field value.

getField(key: string) → Promise<any | null>

Get a sanitized copy of application settings (AI credentials excluded).

getSettings() → Promise<AppSettings>

Get a specific setting field by dot path (e.g. "generalSettings.languageIsoCode").

getSettingsField(path: string) → Promise<any | null>

Modify application settings. Allowed sections: generalSettings, trophySettings, hideSettings, editorSettings, editorToolbarSettings. AI settings cannot be modified.

updateSettings(changes: Partial<Pick<AppSettings, 'generalSettings' | 'trophySettings' | 'hideSettings' | 'editorSettings' | 'editorToolbarSettings'>>) → Promise<void>

Create a backup. Returns the backup ID.

create(name?: string, observations?: string) → Promise<string>

Get a specific backup by ID.

getById(id: string) → Promise<BackupEntry | null>

List all backups.

list() → Promise<BackupEntry[]>

Restore a backup. WARNING: This replaces the current project data.

restore(id: string) → Promise<void>

Subscribe to an event.

on(event: PluginEvent, callback: EventCallback) → void

Unsubscribe from an event.

off(event: PluginEvent, callback: EventCallback) → void

Trigger a file download to the user's device.

exportFile(fileName: string, content: string, mimeType?: string) → Promise<void>

Register this plugin as a book exporter (all files concatenated).

registerBookExporter(config: BookExporterConfig) → Promise<void>

Register this plugin as a file exporter. The convert function is called when the user exports.

registerExporter(config: FileExporterConfig) → Promise<void>

Register this plugin as a project exporter.

registerProjectExporter(config: ProjectExporterConfig) → Promise<void>

Register this plugin as a file importer. The convert function receives raw file data.

registerImporter(config: FileImporterConfig) → Promise<void>

Register this plugin as a project importer.

registerProjectImporter(config: ProjectImporterConfig) → Promise<void>

Get the currently active/focused document, or null if no editor is open.

getActiveDocument() → Promise<OpenDocument | null>

Get all documents currently open in editor tabs.

getOpenDocuments() → Promise<OpenDocument[]>

Get the current text selection in the active editor. Returns null if no editor is open. Positions are ProseMirror document positions (use with insertAt/replaceRange).

getSelection() → Promise<EditorSelection | null>

Get the word count of the active document. Returns 0 if no editor is open.

getWordCount() → Promise<number>

Insert HTML content at a specific position in the active editor.

insertAt(position: number, html: string) → Promise<void>

Replace a range of content in the active editor.

replaceRange(from: number, to: number, html: string) → Promise<void>

Replace the current selection with HTML content. If the selection is empty (cursor only), inserts at the cursor position.

replaceSelection(html: string) → Promise<void>

Clear the console log buffer.

clear() → Promise<void>

Get all stored console log entries. Requires debug.console scope.

getLogs() → Promise<ConsoleEntry[]>

Convert HTML to ProseMirror JSON. Supports standard HTML elements: <p>, <h1>–<h6>, <strong>, <em>, <a>, <ul>, <ol>, <blockquote>, <code>, <table>, etc.

fromHtml(html: string) → Promise<ProseMirrorDocument>

Convert Markdown to ProseMirror JSON. Parses standard Markdown syntax (headings, bold, italic, links, lists, code blocks).

fromMarkdown(markdown: string) → Promise<ProseMirrorDocument>

Convert plain text to ProseMirror JSON. Each line becomes a paragraph node.

fromText(text: string) → Promise<ProseMirrorDocument>

Convert ProseMirror JSON to clean HTML. Returns HTML fragment (no <html>/<body> wrapper). Supports headings, paragraphs, lists, bold, italic, links, images. Accepts a parsed ProseMirrorDocument object or a raw JSON string.

toHtml(json: ProseMirrorDocument | string) → Promise<string>

Convert ProseMirror JSON to Markdown. Uses ATX-style headings (#), bold, *italic*, [links](url). Accepts a parsed ProseMirrorDocument object or a raw JSON string.

toMarkdown(json: ProseMirrorDocument | string) → Promise<string>

Convert ProseMirror JSON to plain text. Extracts text content, discarding all formatting. Accepts a parsed ProseMirrorDocument object or a raw JSON string (as returned by getFileContent()).

toText(json: ProseMirrorDocument | string) → Promise<string>

Perform an HTTP request to an external host (proxied by the host app). Requires the net.fetch scope and the target host must be listed in the plugin manifest's network.domains allow-list (the user approves those domains at install time). Requests to any other host are rejected. Supports exact hosts and leading-wildcard subdomains (*.example.com).

fetch(url: string, options?: NetFetchOptions) → Promise<NetFetchResponse>

getNowPlaying() → Promise<MediaNowPlaying | null>

getState() → Promise<'idle' | 'playing' | 'paused' | 'buffering' | 'ended'>

next() → Promise<void>

pause() → Promise<void>

Play a public YouTube video or playlist (URL or id) in the host's background player.

play(source: string) → Promise<void>

previous() → Promise<void>

resume() → Promise<void>

Set the volume, 0–100.

setVolume(volume: number) → Promise<void>

stop() → Promise<void>