Data types
Every type the plugin SDK hands you or takes back: 65 interfaces and unions, straight from the published type definitions.
On this page
These are the shapes behind the API reference. When a method says
it returns Promise<Character>, this page is what a Character
contains. All of it is read out of tintero-plugin-sdk.d.ts, the same file you
compile against, so your editor and this page cannot disagree.
Known divergences
Found automatically, not hand-picked: places where the published type says one thing and you actually receive another. Your compiler believes the left column. What arrives is the right one. This section empties itself once the source is fixed.
WorldbuildingElement.extraFields - The .d.ts declares
- { key, value }
- You actually receive
- { id, label, type, value }
The host passes through BaseWorldbuildingElement.extraFields unchanged.
Data Types
ProjectMetadata #
id string name string description string | null createdAt number lastModified number path string CharacterWorldbuilding #
species ? string[] factions ? string[] occupations ? string[] locations ? string[] religions ? string[] magicSystems ? string[] languages ? string[] technologies ? string[] groupMember ? string[] groupLeader ? string[] groupFounder ? string[] groupExMember ? string[] groupExLeader ? string[] deityFollower ? string[] deityChampion ? string[] deityClergy ? string[] deityEnemy ? string[] deityBlessed ? string[] deityCursed ? string[] deityExFollower ? string[] creatureTamed ? string[] creatureHunted ? string[] creatureProtected ? string[] creatureEncountered ? string[] creatureCompanion ? string[] creatureFamiliar ? string[] itemOwner ? string[] itemCreator ? string[] itemDiscovered ? string[] itemGuardian ? string[] itemExOwner ? string[] itemSeeker ? string[] eventParticipant ? string[] eventKeyFigure ? string[] eventCausedBy ? string[] eventWitness ? string[] eventVictim ? string[] eventHero ? string[] CharacterVariant #
id string name string description ? string position ? number overrides Record<string, any> Partial overrides of character fields for this variant.
createdAt number updatedAt ? number Character #
id string name string firstName ? string lastName ? string pronouns ? string[] aka ? string[] physicalDescription ? string psychologicalDescription ? string portrait ? string landscape ? string color ? string gender ? string age ? string birthdate ? string birthplace ? string traits ? string[] goals ? string[] fears ? string[] backstory ? string notes ? string tags ? string[] createdAt number updatedAt ? number relationships ? Relationship [] variants ? CharacterVariant [] worldbuilding ? CharacterWorldbuilding Relationship #
characterId string type string description ? string isBidirectional ? boolean inverseType ? string WorldbuildingType #
Known worldbuilding element types. Plugins may encounter other custom types.
| 'species' | 'faction' | 'occupation' | 'location' | 'religion' | 'magic-system' | 'technology' | 'language' | 'event' | 'creature' | 'item' | 'group' | 'deity' | 'custom'One field of this type does not match what you receive.
WorldbuildingElement #
id string name string type WorldbuildingType | string One of the known WorldbuildingType values, or a custom string.
description ? string portrait ? string Reference to the element's portrait image (fileName or relativePath). Resolve with tintero.project.getImageData().
landscape ? string Reference to the element's landscape/banner image (fileName or relativePath). Resolve with tintero.project.getImageData().
isFavorite ? boolean tags ? string[] color ? string createdAt number updatedAt ? number notes ? string extraFields ? { key: string; value: string }[] WritingMode #
Writing mode for files and documents.
'prose' | 'screenplay' | 'theatre'FileMetadata #
id string name string title ? string location string treePath ? string order ? number | null status ? string | null createdAt number lastModified number hash ? string links ? string[] color ? string customIcon ? string wordNumber ? number keywords ? string[] customMetadata ? Record<string, string> writingMode ? WritingMode DocMetadata #
id string name string title string location string treePath string createdAt number lastModified number links ? string[] color ? string customIcon ? string wordNumber ? number keywords ? string[] customMetadata ? Record<string, string> writingMode ? WritingMode Note #
id string fileId string | null type string location string textAssociated string | null content ? string PlotGridColumn #
id string name string position number PlotGridCell #
id string type string columnId string rowIndex number referenceId ? string content ? string color ? string PlotGrid #
id string name string columns PlotGridColumn [] rowCount number cells PlotGridCell [] createdAt number lastModified number CardboardCell #
id string type string position { row: number; col: number } referenceId ? string content ? string imageUrl ? string For image cells: reference to the image (fileName or relativePath). Resolve with tintero.project.getImageData().
color ? string checked ? boolean title ? string CardboardGrid #
id string name string rows number cols number cells CardboardCell [] createdAt number lastModified number Collection #
id string name string items { id: string; type: string }[] ImageInfo #
id string title string fileName string relativePath string size number mimeType string width ? number height ? number createdAt ? number Creation timestamp in epoch milliseconds.
WritingGoal #
id string type string "words" | "chapters" | "chaptersCreated" | "characters" | "worldbuilding" | "streak" | "minutes"
cadence string "daily" | "weekly" | "monthly" | "total"
target number title ? string createdAt number archivedAt ? number | null Soft-delete marker; archived goals are kept for sync merges.
WordCountLog #
dayTimestamp number Start-of-day epoch ms for the logged day.
count number objective number WritingMinutesLog #
dayTimestamp number Start-of-day epoch ms for the logged day.
minutes number TimelineNote #
id string text string color string position number TimelineBlock #
id string fileId string sceneId ? string childTimelineId ? string startCol number spanCols number color ? string characterId ? string Linked project character id.
worldbuildingId ? string Linked project worldbuilding element id.
TimelineLane #
id string name string collapsed boolean customHeight ? number blocks TimelineBlock [] notes TimelineNote [] milestones TimelineNote [] Timeline #
id string name string parentId ? string lanes TimelineLane [] unassignedNotes TimelineNote [] customWidth ? number createdAt number lastModified number FlowMapTodo #
id string text string done boolean FlowMapNode #
id string label string x number y number type string "circle" | "square" | "document" | "todo-list" | "simple-list" | "diamond" | custom string
color string extendedText ? string noteColor ? string linkedDocument ? string Linked project document fileId.
linkedCharacterId ? string Linked project character id.
linkedWorldbuildingId ? string Linked project worldbuilding element id.
todoList ? FlowMapTodo [] width ? number height ? number customData ? any FlowMapConnection #
id string fromNodeId string toNodeId string arrowType string "simple" | "bidirectional" | "unidirectional-forward" | "unidirectional-backward" | "dotted"
label ? string startEdgePosition ? number endEdgePosition ? number color ? string FlowMap #
id string name string nodes FlowMapNode [] connections FlowMapConnection [] createdAt number lastModified number CustomFieldDef #
id string name string label string type string "text" | "textarea" | "checkbox" | "relationship"
placeholder ? string description ? string defaultValue ? any order ? number CustomWorldbuildingTemplate #
id string name string description ? string icon string color string fields CustomFieldDef [] createdAt number updatedAt number archived ? boolean tags ? string[] version ? number FileSnapshot #
Scene #
id string name ? string povCharacterId string | null charactersInScene ? string[] | null objectsInScene ? string[] | null type string "main_continuity" | "flashback" | "dream" | "vision" | "memory" | "prologue" | "epilogue" | "interlude" | "montage"
locationId string | null createdAt number updatedAt number startOffset ? number endOffset ? number notes ? string BackupEntry #
id string name string timestamp number observations ? string type 'automatic' | 'manual' Write input types
CharacterInput #
name string firstName ? string lastName ? string pronouns ? string[] aka ? string[] physicalDescription ? string psychologicalDescription ? string portrait ? string Reference to the character's portrait image (fileName or relativePath).
landscape ? string Reference to the character's landscape/banner image (fileName or relativePath).
color ? string gender ? string age ? string birthdate ? string birthplace ? string traits ? string[] goals ? string[] fears ? string[] backstory ? string notes ? string tags ? string[] WorldbuildingInput #
name string type string description ? string tags ? string[] color ? string notes ? string NoteInput #
location string type ? string fileId ? string textAssociated ? string content ? string FileInput #
name string File name (required).
treePath ? string Folder tree path (e.g. "Chapter 1"). Defaults to root.
writingMode ? WritingMode Writing mode: 'prose' | 'screenplay' | 'theatre'. Defaults to 'prose'.
content ? string Optional initial HTML content.
color ? string Color tag.
customIcon ? string Custom emoji icon.
keywords ? string[] Keywords/tags.
customMetadata ? Record<string, string> Free-form metadata.
status ? string Workflow status (e.g. "draft", "review").
FileMetaUpdate #
name ? string title ? string color ? string customIcon ? string keywords ? string[] customMetadata ? Record<string, string> writingMode ? WritingMode status ? string order ? number treePath ? string DocInput #
name string Document name (required).
treePath ? string Folder tree path. Defaults to root.
writingMode ? WritingMode Writing mode. Defaults to 'prose'.
content ? string Optional initial HTML content.
color ? string Color tag.
customIcon ? string Custom emoji icon.
keywords ? string[] Keywords/tags.
customMetadata ? Record<string, string> Free-form metadata.
DocMetaUpdate #
name ? string title ? string color ? string customIcon ? string keywords ? string[] customMetadata ? Record<string, string> writingMode ? WritingMode treePath ? string FolderInfo #
id string title string treePath string color ? string customIcon ? string Application Settings types
GeneralSettings #
languageIsoCode string selectedTheme string sidebarLength number editorZoom number spellCheckLanguage string dateFormat string timeFormat string autoDetectLanguage boolean fontSize number | null distractionFreeMode boolean highlightCurrentLine boolean showWordCount boolean useDialogWhenCreatingFiles boolean appMode 'creative' | 'study' | 'minimal' clickFileOpensSameTab boolean displayChapterOrder boolean showNativeDecorators boolean TrophySettings #
dailyObjective number weeklyObjective number objectiveType string objectiveReminders boolean showRealTimeProgress boolean streakTracking boolean reminderTime string showAchievements boolean achievementNotifications boolean HideSettings #
showSidebar boolean editorShowSidebar boolean showStatusBar boolean showEditorUnderBar boolean visibleSidebarFiles boolean visibleSidebarCharacters boolean visibleSidebarWorldbuilding boolean visibleSidebarNotes boolean visibleSidebarAchievements boolean visibleSidebarBetaShares boolean EditorSettings #
defaultFontFamily string | null maxCharacters number | null defaultFontSize number | null intelligentQuotes ? boolean intelligentDialog ? boolean autoSave ? boolean EditorToolbarSettings #
disableDistractionFreeMode ? boolean disableZoom ? boolean disableBold ? boolean disableItalic ? boolean disableStrikethrough ? boolean disableHighlight ? boolean disableRemoveFormat ? boolean disableHeadings ? boolean disableAlignLeft ? boolean disableAlignCenter ? boolean disableAlignRight ? boolean disableJustify ? boolean disableUnorderedList ? boolean disableOrderedList ? boolean disableBlockquote ? boolean disableCodeBlock ? boolean disableInlineCode ? boolean disableFootnote ? boolean disableTable ? boolean disableImage ? boolean disableDocumentLink ? boolean disableHorizontalRule ? boolean SanitizedAiSettings #
Sanitized AI settings exposed to plugins. Sensitive fields (host, port, lastUsedModels) are excluded.
serverType 'ollama' | 'lm-studio' hide ? boolean selectedModel string temperature number maxTokens number AppSettings #
The full application settings object returned by tintero.app.getSettings().
generalSettings GeneralSettings trophySettings TrophySettings hideSettings HideSettings editorSettings EditorSettings editorToolbarSettings EditorToolbarSettings aiSettings SanitizedAiSettings AI settings are sanitized. Host, port, and lastUsedModels are stripped.
Dialog options
DialogOptions #
title ? string width ? number height ? number data ? any Notification types
NotificationType #
'info' | 'success' | 'warning' | 'error'Export/Import config
ExportResult #
data string encoding ? 'text' | 'base64' mimeType ? string FileExporterConfig #
formatName string extension string mimeType ? string convert (jsonContent: string) => string | ExportResult | Promise<string | ExportResult > Receives the file content as a ProseMirror/TipTap JSON string. Use JSON.parse() or tintero.convert to work with it.
BookExporterConfig #
formatName string extension string mimeType ? string convert (documents: string[], metadata: ProjectMetadata ) => string | ExportResult | Promise<string | ExportResult > Each element of documents is a ProseMirror/TipTap JSON string for one file.
ProjectExporterConfig #
formatName string extension string mimeType ? string convert (project: any) => string | ExportResult | Promise<string | ExportResult > FileImporterConfig #
formatName string extensions string[] formatDescription ? string convert (data: string, fileName: string) => string | Promise<string> ProjectImporterConfig #
formatName string extensions string[] formatDescription ? string convert (data: string, fileName: string) => any | Promise<any> Editor types
EditorSelection #
from number Start position of the selection in the ProseMirror document.
to number End position of the selection. Same as from when no text is selected.
text string The selected text, or empty string if nothing is selected.
empty boolean Whether the selection is empty (cursor only, no text selected).
OpenDocument #
id string File or document ID.
name string Display name (file name).
writingMode ? WritingMode Writing mode if set.
color ? string Color tag.
customIcon ? string Custom emoji icon.
isActive boolean Whether this document is the currently active/focused one.
Debug / Console types
ConsoleEntry #
level 'log' | 'warn' | 'error' | 'info' args string[] source string Source identifier: 'app' for host logs, or a plugin ID for plugin logs.
timestamp number ProseMirror JSON type
ProseMirrorNode #
A ProseMirror/TipTap document JSON structure.
The top-level node has type: "doc" with an array of child nodes.
Each node has a type (e.g. "paragraph", "heading"), optional content,
optional attrs, and text nodes have a text string with optional marks.
type string content ? ProseMirrorNode [] text ? string marks ? { type: string; attrs?: Record<string, any> }[] attrs ? Record<string, any> ProseMirrorDocument #
type 'doc' content ProseMirrorNode [] Format Conversion API
NetFetchOptions #
method ? 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' HTTP method. Defaults to 'GET'. Allowed: GET, POST, PUT, PATCH, DELETE, HEAD.
headers ? Record<string, string> Request headers.
body ? string Request body (already serialized as a string) for non-GET/HEAD methods.
responseType ? 'text' | 'json' | 'base64' How to decode the response body. Defaults to 'text'. Use 'base64' to
fetch binary (e.g. an image): the host proxies the request and returns the
bytes base64-encoded, so you can render it as a data: URI without relaxing
the plugin CSP.
NetFetchResponse #
ok boolean status number statusText string headers Record<string, string> body any Decoded body: a string for 'text', a parsed value for 'json', a base64 string for 'base64'.
MediaNowPlaying #
title ? string videoId ? string Where these come from
65 types, of which 42 appear directly in a method signature; the rest are reached through another type. Extracted from the published definitions alongside the 97 methods that use them, so a type renamed in Tintero is renamed here on the next sync rather than lingering as a shape nobody returns any more.