version

readonly version: string

Semantic version of this API. Check it with isCompatible (or use getBooks).

listBooks

listBooks(which: number[] | {
    shelf: string;
}): Promise<BookSummary[]>

Books by Calibre id (in the order asked), or a shelf's books (by Calibre id). Works from the Content Server, or read-only from the library file when the server is off and a library folder is set. Rejects with book-missing naming any id Calibre doesn't have.

bookFile

bookFile(id: number, format: BookFormat, opts?: BookFileOptions): Promise<ArrayBuffer | null>

A book file's bytes, through the Content Server. With { convert: true }, an EPUB the book lacks is made from its AZW3 or MOBI after the user agrees (null if they decline). Rejects with server-off when the server is off, even if the library file is readable.

pdfText

pdfText(id: number): Promise<string>

A PDF's text, page by page (pages separated by a blank line), through Obsidian's PDF.js.

shelfMembers

shelfMembers(shelf: string): Promise<number[]>

The Calibre ids of the books on a shelf, ascending: by the shelf's rule, pinned, not excluded (the same test as the shelf's Base). A shelf is named by its collection_id, or its note's name or path. Book notes without a calibre_id aren't included.

calibreChecks

calibreChecks(): Promise<CalibreChecks>

The Calibre settings Books & Shelves depends on, checked against the Content Server now: that it answers, that any login works, that the library exists, and that it allows changes (needed to convert a book or write to it). Each check that fails says how to set it right in Calibre. Never rejects: a server that doesn't answer is a failed check. Since 0.2.

isCompatible

declare function isCompatible(actual: string, wanted: string): boolean;

True when a consumer built against wanted can use an API at actual: same major and a minor at least as new. Before 1.0, minors break by default, so 0.x serves only the minors it promises (0.1 and up). The same rule as Model Hub's, used for both directions: this plugin's API, and the Hub API this plugin asks for.

getBooks

declare function getBooks(app: unknown, wanted: string): GetBooksResult;

Finds Books & Shelves in this vault and checks its API version against the one you built for.

onBooksReady

declare function onBooksReady(app: unknown, plugin: {
    registerEvent(ref: unknown): void;
}, wanted: string, cb: (books: BooksApi) => void): void;

Runs cb with the API now if Books & Shelves is loaded (and compatible with wanted), and again each time it loads: it fires books-and-shelves:ready on the workspace at the end of its onload. The listener is registered on your plugin, so it stops when your plugin unloads.

onBooksReady(this.app, this, '0.1.0', (books) => (this.books = books));

BOOKS_API_VERSION

declare const BOOKS_API_VERSION = "0.2.0";

Semantic version of Books & Shelves' public API. Consumers check it before calling anything else.

BOOKS_PLUGIN_ID

declare const BOOKS_PLUGIN_ID = "books-and-shelves";

BOOKS_READY_EVENT

declare const BOOKS_READY_EVENT = "books-and-shelves:ready";

The workspace event Books & Shelves fires each time it loads, with its API: at startup, and when the user disables and enables it again. onBooksReady listens for it.