audiobookshelf-mcp 0.2.0 → 0.4.0

package/README.md

@@ -1,13 +1,19 @@
 # audiobookshelf-mcp
 
+<!-- badges: start -->
+
 [![CI](https://img.shields.io/github/actions/workflow/status/ni-c/audiobookshelf-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/audiobookshelf-mcp/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ni-c/audiobookshelf-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/ni-c/audiobookshelf-mcp)
+<a href="https://socket.dev/npm/package/audiobookshelf-mcp"><img src="https://socket.dev/api/badge/npm/package/audiobookshelf-mcp" alt="Socket supply-chain report" height="20"></a>
+[![Glama score](https://glama.ai/mcp/servers/ni-c/audiobookshelf-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ni-c/audiobookshelf-mcp)
+<br>
 [![npm version](https://img.shields.io/npm/v/audiobookshelf-mcp)](https://www.npmjs.com/package/audiobookshelf-mcp)
-[![npm downloads](https://img.shields.io/npm/dm/audiobookshelf-mcp)](https://www.npmjs.com/package/audiobookshelf-mcp)
-[![node](https://img.shields.io/node/v/audiobookshelf-mcp)](https://nodejs.org)
-[![license](https://img.shields.io/npm/l/audiobookshelf-mcp)](LICENSE)
-[![container](https://img.shields.io/badge/ghcr.io-ni--c%2Faudiobookshelf--mcp-blue)](https://github.com/ni-c/audiobookshelf-mcp/pkgs/container/audiobookshelf-mcp)
-[![docs](https://img.shields.io/badge/docs-audiobookshelf--mcp.ni--c.de-informational)](https://audiobookshelf-mcp.ni-c.de)
+[![container image](https://img.shields.io/badge/ghcr.io-ni--c%2Faudiobookshelf--mcp-4f46e5?logo=docker&logoColor=white)](https://github.com/ni-c/audiobookshelf-mcp/pkgs/container/audiobookshelf-mcp)
+[![HTTP via mcp-hub](https://img.shields.io/badge/HTTP-via%20mcp--hub-4f46e5?logo=modelcontextprotocol&logoColor=white)](https://mcp-hub.ni-c.de)
+<br>
+[![docs](https://img.shields.io/badge/docs-audiobookshelf--mcp.ni--c.de-4f46e5?logo=readthedocs&logoColor=white)](https://audiobookshelf-mcp.ni-c.de)
 [![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)
+<!-- badges: end -->
 
 A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for
 [Audiobookshelf](https://www.audiobookshelf.org/), the self-hosted audiobook and
@@ -35,6 +41,21 @@ reliably from eight than from forty-four — see
 
 <img src="https://audiobookshelf-mcp.ni-c.de/demo.gif" alt="Terminal recording: the server reports 44 tools, lists library items as a compact projection, and answers the first delete_collection call with a single-use confirmation token instead of deleting anything" width="800">
 
+## What makes it different
+
+**Every response is a projection, not the raw object.** An expanded library item
+carries every audio file, track and chapter with full ffprobe metadata. The media
+tools answer with a compact shape instead, and `detail="full"` is there for when
+the raw object really is what you want.
+
+**Twenty-nine of the forty-four tools only read.** `AUDIOBOOKSHELF_READ_ONLY=true`
+registers those and nothing else, so a write tool is absent from `tools/list`
+rather than refused when it is called.
+
+**The six tools that take something out ask a person first**, through MCP
+elicitation — a dialog the model cannot answer on its behalf, falling back to a
+single-use token bound to the exact targets where the client cannot show one.
+
 ## Requirements
 
 - Node.js 22 or newer
@@ -59,6 +80,7 @@ once, at creation.
 | `AUDIOBOOKSHELF_INSECURE_TLS` | no       | `true` accepts self-signed certificates — scoped to this connection, not process-wide   |
 | `AUDIOBOOKSHELF_ALLOW_TOOLS`  | no       | Comma-separated tool names, `list_*` prefixes, or `essential` for a curated preset      |
 | `AUDIOBOOKSHELF_DENY_TOOLS`   | no       | Same syntax; removed from whatever `AUDIOBOOKSHELF_ALLOW_TOOLS` left                    |
+| `ELICITATION`                 | no       | `false` replaces the approval dialog with the two-call token. **Not prefixed**          |
 
 The server starts without configuration: it completes the MCP handshake and lists
 its tools, and every call then fails with the setup instructions. That is
@@ -86,7 +108,9 @@ If you run several of these servers at once, [mcp-hub](https://mcp-hub.ni-c.de)
 is the other answer — its `/hub` endpoint replaces every server's tools with six
 meta-tools.
 
-## Install
+## Installation
+
+### Claude Code
 
 ```sh
 claude mcp add audiobookshelf \
@@ -95,7 +119,9 @@ claude mcp add audiobookshelf \
   -- npx -y audiobookshelf-mcp
 ```
 
-Claude Desktop (`claude_desktop_config.json`):
+### Claude Desktop
+
+`claude_desktop_config.json`:
 
 ```json
 {
@@ -112,7 +138,9 @@ Claude Desktop (`claude_desktop_config.json`):
 }
 ```
 
-Codex (`~/.codex/config.toml`):
+### Codex
+
+`~/.codex/config.toml`:
 
 ```toml
 [mcp_servers.audiobookshelf]
@@ -121,7 +149,9 @@ args = ["-y", "audiobookshelf-mcp"]
 env = { AUDIOBOOKSHELF_URL = "https://abs.example.com", AUDIOBOOKSHELF_API_KEY = "…" }
 ```
 
-Container (multi-arch, with SBOM and build provenance):
+### Docker
+
+Multi-arch, with SBOM and build provenance:
 
 ```sh
 docker run -i --rm \
@@ -135,8 +165,61 @@ publish. More client recipes, including how to keep the key off the `docker run`
 command line, are in the
 [client guide](https://audiobookshelf-mcp.ni-c.de/guide/clients).
 
+### Through mcp-hub
+
+A client that cannot spawn a local process — ChatGPT connectors, Claude on the web,
+Cursor, LibreChat — reaches audiobookshelf-mcp through [mcp-hub](https://mcp-hub.ni-c.de): one
+container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login
+behind a single password and long-lived tokens for the clients that cannot do OAuth. Its
+`/hub` endpoint puts every server behind six meta-tools, so one connector reaches all of
+them without N×tool schemas in the model's context, and it speaks both protocol revisions
+— a question this server asks travels through it to the person at the far end.
+
+Its `/config/mcp.json` uses Claude Code's format, so the entry is the one you already
+have:
+
+```json
+{
+  "mcpServers": {
+    "audiobookshelf": {
+      "command": "npx",
+      "args": ["-y", "audiobookshelf-mcp"],
+      "env": { "AUDIOBOOKSHELF_ALLOW_TOOLS": "essential" },
+      "denyTools": ["delete_*"]
+    }
+  }
+}
+```
+
+`allowTools` and `denyTools` there are the hub's **own** per-server filter, which is not
+the same thing as `*_ALLOW_TOOLS` in `env` — the difference, and the mistake it invites,
+are in the [client guide](https://audiobookshelf-mcp.ni-c.de/guide/clients#through-mcp-hub).
+
 ## Tools
 
+Every tool declares an `outputSchema` and answers with `structuredContent`
+alongside the text block, so a client can use the result without parsing prose.
+Seven tools that answered with a sentence — _"Collection col_1 deleted."_ — now
+answer with the fields as well.
+
+The tools that report library metadata carry `untrusted: true` and
+`source: "audiobookshelf"` as fields: book descriptions pulled from metadata
+providers, podcast feed summaries and episode titles are all written by someone
+else, and so are the bookmark titles and selected tags of an account and the
+titles of a library's longest and largest items. The rest are without it — an
+id this server was given, a position it was asked to store, the version string
+of the instance, and the library names and folder paths the operator typed.
+
+The documents are described as open objects with the top-level keys this server
+builds. `detail: "full"` hands the API record back whole, so the same tool
+answers with far more keys than it names — and the SDK validates each result
+against its schema before it goes out, which is exactly why a strict shape would
+be wrong here.
+
+`get_personalized_shelves` answers `{items: [...]}` rather than the bare array
+the API sends: a schema whose root is an array is served to a 2025-era client
+rewritten as `{result: …}`, so it would otherwise answer in two shapes.
+
 ### Reading
 
 | Tool                                  | What it does                                                                                        |
@@ -168,23 +251,45 @@ command line, are in the
 
 ### Writing
 
-| Tool                                                            | What it does                                                            |
-| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| `set_media_progress`                                            | Set position, mark finished or unfinished, hide from Continue Listening |
-| `delete_media_progress`                                         | Delete a progress record — needs a confirmation token                   |
-| `create_bookmark` / `update_bookmark` / `delete_bookmark`       | Named positions in a book                                               |
-| `create_collection` / `update_collection` / `delete_collection` | Collections; delete needs a confirmation token                          |
-| `add_books_to_collection` / `remove_books_from_collection`      | Collection membership                                                   |
-| `create_playlist` / `update_playlist` / `delete_playlist`       | Playlists; delete needs a confirmation token                            |
-| `add_items_to_playlist` / `remove_items_from_playlist`          | Playlist membership                                                     |
+| Tool                                                               | What it does                                                            |
+| ------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| `set_media_progress`                                               | Set position, mark finished or unfinished, hide from Continue Listening |
+| `delete_media_progress` 👤                                         | Delete a progress record — the listening history of that item           |
+| `create_bookmark` / `update_bookmark` / `delete_bookmark` 👤       | Named positions in a book                                               |
+| `create_collection` / `update_collection` / `delete_collection` 👤 | Collections                                                             |
+| `add_books_to_collection` / `remove_books_from_collection` 👤      | Collection membership                                                   |
+| `create_playlist` / `update_playlist` / `delete_playlist` 👤       | Playlists                                                               |
+| `add_items_to_playlist` / `remove_items_from_playlist` 👤          | Playlist membership                                                     |
+
+👤 asks a person through MCP elicitation · falls back to a two-call
+`confirm_token` where the client cannot show a dialog.
 
 ### Response size
 
 Audiobookshelf returns very large objects — an expanded library item carries every
 audio file, track and chapter with full ffprobe metadata. Every tool that returns
 media therefore answers with a compact projection by default and accepts
-`detail: "full"` for the raw object. List tools are capped at 100 entries per call
-and say how to page on when more match.
+`detail: "full"` for the raw object.
+
+Three bounds, because one is not enough:
+
+- **A response ceiling of 5 MB.** `content-length` is checked before a byte is
+  read and a chunked body is counted while reading, so an oversized answer is
+  refused rather than parsed.
+- **A result ceiling of 100 000 bytes**, applied in `jsonResult` — so it covers
+  `detail: "full"` too. Whole entries are dropped, never characters: a truncated
+  document is not a smaller answer, it is an unparseable one. The result then
+  carries a `truncated` block naming what to call instead.
+- **A cap on embedded members.** A compact collection or playlist embeds the
+  first 25 of its books or entries and reports the real count; `get_collection`
+  and `get_playlist` return the whole membership for one of them.
+
+`list_library_items` pages properly, with `limit` and `page`. Seven listing tools
+have neither — `list_libraries`, `list_authors`, `list_tags`, `list_genres`,
+`list_collections`, `list_playlists` and `list_bookmarks` — because the
+Audiobookshelf routes behind them return everything in one answer and take no
+paging parameters. `library_id` narrows the two collection routes; the rest are
+bounded by the ceilings above.
 
 ### Filtering
 
@@ -199,20 +304,44 @@ filter_group="progress", filter_value="finished" | "in-progress" | "not-started"
 filter_group="issues"    (standalone, no value)
 ```
 
+## Not exposed, on purpose
+
+**No playback.** Pausing, seeking and playing are a session state machine that
+belongs in a real client. `set_media_progress` covers "mark this finished" and
+"jump me to chapter 12"; your phone does the playing.
+
+**No administration, even with an admin key.** There is no tool for user
+management, server settings, backups, cache purging, filesystem browsing, library
+or item deletion, metadata rewriting or file uploads. Those endpoints exist in
+Audiobookshelf; they are simply not wired up here, because the blast radius of a
+confused or manipulated model is bounded by the tool list.
+
 ## Safety
 
 - **Read-only mode.** `AUDIOBOOKSHELF_READ_ONLY=true` does not register the write
   tools at all, rather than refusing them at call time.
-- **Confirmation tokens.** `delete_collection`, `delete_playlist` and
-  `delete_media_progress` answer the first call with a single-use token that is
-  bound to the target id and expires after five minutes; only a second call
-  carrying that token performs the deletion. A plain `confirm: true` flag could be
-  set by the model on the first try, or be talked into it by text coming out of
-  the library. Operations that are cheap to undo — removing an item from a
-  collection, deleting a bookmark — are marked destructive but do not require a
-  token.
+- **A person is asked, not just told.** The eight tools that can take something
+  out — the three deletes, `delete_bookmark`, `remove_books_from_collection`,
+  `remove_items_from_playlist`, and `update_collection` / `update_playlist` when
+  they are asked to reorder, which replaces an order nobody can reconstruct —
+  raise a real dialog through MCP elicitation,
+  which the model cannot answer on its behalf. A plain `confirm: true` flag could
+  be set by the model on the first try, or be talked into it by text coming out
+  of the library.
+
+  Where the client cannot show a dialog they fall back to a single-use token
+  bound to the exact targets and expiring after five minutes. That fallback
+  proves the call was made twice with the same arguments and nothing more, and
+  the text says so rather than implying somebody approved. `ELICITATION=false`
+  takes it deliberately; it never removes the guard. See
+  [Asking a person](https://audiobookshelf-mcp.ni-c.de/guide/approval).
+
 - **Confirmation prompts never quote API content.** Collection and playlist names
-  are user-supplied text and are read by a model, so the prompts name only ids.
+  are user-supplied text and are read by a model, so the prompts name ids and
+  counts only.
+- **A 200 that is not JSON is an error.** Returning the body as a string made an
+  SSO portal or a captive proxy in front of the instance look like an empty
+  library rather than like a failure.
 - **Untrusted content is marked.** Book descriptions come from metadata providers
   and podcast summaries come from RSS feeds — third parties write them. Every
   result carrying such content is labelled as data, not instructions.
@@ -234,11 +363,16 @@ One caveat that comes from Audiobookshelf itself: removing the _last_ entry from
 playlist deletes the playlist. `remove_items_from_playlist` says so in its result
 when it happens.
 
+## Documentation
+
+The full guide, tool reference and security notes live at
+**[audiobookshelf-mcp.ni-c.de](https://audiobookshelf-mcp.ni-c.de)** (source in [`docs/`](docs/)).
+
 ## Development
 
 ```sh
 npm install
-npm run lint          # eslint + prettier --check
+npm run lint          # oxlint + prettier --check
 npm run build         # tsc
 npm test              # vitest
 npm run test:coverage # with thresholds
@@ -289,4 +423,4 @@ rather than a public issue; the policy is in [SECURITY.md](SECURITY.md).
 
 ## License
 
-MIT
+[MIT](LICENSE) © Willi Thiel

package/dist/api.d.ts

@@ -4,6 +4,36 @@ export declare class AudiobookshelfApiError extends Error {
     readonly body: string;
     constructor(status: number, body: string, method: string, path: string);
 }
+/** Thrown when a response is larger than this server is willing to read. */
+export declare class ResponseTooLargeError extends Error {
+    constructor(path: string, limit: number);
+}
+/**
+ * Thrown when a 200 carries something other than JSON.
+ *
+ * Returning the body instead would send an HTML login page into `listFrom`,
+ * which finds neither an array nor an envelope and answers `[]` — so
+ * `list_libraries` reports "you have no libraries" where the truth is that an
+ * SSO portal or a misconfigured reverse proxy answered instead of the API. A
+ * swallowed error replaced by a plausible wrong answer is worse than an error.
+ */
+export declare class UnexpectedContentTypeError extends Error {
+    constructor(path: string, contentType: string);
+}
+export interface RequestOptions {
+    /**
+     * Accept a body that is not JSON.
+     *
+     * Only for the five routes that are known to answer `200 text/plain "OK"`
+     * rather than a document — verified against 2.29.0:
+     * `DELETE /api/collections/{id}`, `DELETE /api/playlists/{id}`,
+     * `PATCH /api/me/progress/{id}`, `DELETE /api/me/progress/{id}` and
+     * `DELETE /api/me/item/{id}/bookmark/{time}`. Every one of them is a mutation
+     * whose caller ignores the value, so the honest thing is to say so at the
+     * call site rather than to weaken the check for everything.
+     */
+    text?: boolean;
+}
 /** Minimal client for the Audiobookshelf REST API. */
 export declare class AudiobookshelfApi {
     private readonly config;
@@ -15,11 +45,11 @@ export declare class AudiobookshelfApi {
      */
     private readonly insecureDispatcher?;
     constructor(config: Config);
-    request(method: string, path: string, body?: unknown): Promise<unknown>;
-    get(path: string): Promise<unknown>;
-    post(path: string, body?: unknown): Promise<unknown>;
-    patch(path: string, body?: unknown): Promise<unknown>;
-    delete(path: string): Promise<unknown>;
+    request(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<unknown>;
+    get(path: string, options?: RequestOptions): Promise<unknown>;
+    post(path: string, body?: unknown, options?: RequestOptions): Promise<unknown>;
+    patch(path: string, body?: unknown, options?: RequestOptions): Promise<unknown>;
+    delete(path: string, options?: RequestOptions): Promise<unknown>;
 }
 /**
  * Guards an id that ends up in a URL path. Path traversal here would let a

package/dist/api.js

@@ -1,6 +1,26 @@
 import { Agent, fetch as undiciFetch, } from 'undici';
 import { missingConfigKeys, missingConfigMessage, } from './config.js';
+import { assertHeaderValue, quoted } from './clean.js';
 const REQUEST_TIMEOUT_MS = 15_000;
+/**
+ * Ceiling on an error body.
+ *
+ * Its own number, far below the success ceiling: a 401 from a reverse proxy is
+ * a login page, and reading five megabytes of it to quote two thousand
+ * characters is work an unauthenticated answer should not be able to buy.
+ */
+const MAX_ERROR_BYTES = 64 * 1024;
+/**
+ * Ceiling on a single upstream response.
+ *
+ * Not a theoretical number. `/api/collections` has no pagination at all, and a
+ * collection carries every one of its books expanded — a shared server with
+ * forty collections of three hundred books answers in double-digit megabytes,
+ * and `response.text()` followed by `JSON.parse` holds roughly three copies of
+ * that at once. The documented 95 kB of `/api/me/listening-stats` is the
+ * harmless end of the same range.
+ */
+const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
 export class AudiobookshelfApiError extends Error {
     status;
     body;
@@ -11,6 +31,74 @@ export class AudiobookshelfApiError extends Error {
         this.name = 'AudiobookshelfApiError';
     }
 }
+/** Thrown when a response is larger than this server is willing to read. */
+export class ResponseTooLargeError extends Error {
+    constructor(path, limit) {
+        super(`the Audiobookshelf response for ${path} exceeds the ` +
+            `${Math.round(limit / 1024 / 1024)} MB ceiling and was not read. ` +
+            'Narrow the request — most listing tools take limit and page, and ' +
+            'library_id restricts a server-wide listing to one library.');
+        this.name = 'ResponseTooLargeError';
+    }
+}
+/**
+ * Thrown when a 200 carries something other than JSON.
+ *
+ * Returning the body instead would send an HTML login page into `listFrom`,
+ * which finds neither an array nor an envelope and answers `[]` — so
+ * `list_libraries` reports "you have no libraries" where the truth is that an
+ * SSO portal or a misconfigured reverse proxy answered instead of the API. A
+ * swallowed error replaced by a plausible wrong answer is worse than an error.
+ */
+export class UnexpectedContentTypeError extends Error {
+    constructor(path, contentType) {
+        super(`Audiobookshelf answered ${path} with "${contentType || 'no content type'}" ` +
+            'instead of JSON. A 200 that is not JSON usually means something in ' +
+            'front of the instance answered instead of the API — an SSO portal, a ' +
+            'captive proxy or a login page. Check AUDIOBOOKSHELF_URL.');
+        this.name = 'UnexpectedContentTypeError';
+    }
+}
+/**
+ * Reads a response body with a hard byte ceiling.
+ *
+ * Both halves matter: `content-length` catches an oversized answer before a
+ * single byte is read, and the streaming count catches a chunked response,
+ * which declares no length at all.
+ */
+async function readCapped(response, maxBytes, allowTruncation) {
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxBytes && !allowTruncation) {
+        // Nothing has been read yet, so the body can simply be discarded.
+        await response.body?.cancel();
+        return { text: '', truncated: true };
+    }
+    const body = response.body;
+    if (!body)
+        return { text: '', truncated: false };
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    let truncated = false;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value === undefined)
+            continue;
+        if (total + value.byteLength > maxBytes) {
+            // `maxBytes - total` is exactly the remaining budget, and the `>` above
+            // makes an exactly-maxBytes response legal rather than truncated.
+            chunks.push(value.subarray(0, maxBytes - total));
+            truncated = true;
+            await reader.cancel();
+            break;
+        }
+        chunks.push(value);
+        total += value.byteLength;
+    }
+    return { text: Buffer.concat(chunks).toString('utf8'), truncated };
+}
 /** Minimal client for the Audiobookshelf REST API. */
 export class AudiobookshelfApi {
     config;
@@ -30,7 +118,7 @@ export class AudiobookshelfApi {
             });
         }
     }
-    async request(method, path, body) {
+    async request(method, path, body, options = {}) {
         // The credentials are only required here, not at startup, so the server can
         // still be started and introspected without them.
         const missing = missingConfigKeys(this.config);
@@ -53,6 +141,18 @@ export class AudiobookshelfApi {
             headers['Content-Type'] = 'application/json';
             init.body = JSON.stringify(body);
         }
+        // Before `fetch` sees them, and after the body branch has added its own.
+        // undici refuses a header value carrying a control character with
+        // `Headers.append: "<value>" is an invalid header value.` — the whole
+        // value, quoted — and this server's Authorization value *is* the API key.
+        // That TypeError reaches `run`, which answers with its message, so the key
+        // would land in the model's context because of a line break in a pasted
+        // credential. `loadConfig` refuses that shape at startup; this is the
+        // second half, because a Config can be built without it and the tests do
+        // exactly that.
+        for (const [name, value] of Object.entries(headers)) {
+            assertHeaderValue(name, value);
+        }
         const url = `${this.baseUrl}${path}`;
         // The insecure dispatcher requires undici's own fetch; the default path uses
         // the (stubbable) global fetch so tests can intercept it.
@@ -62,32 +162,48 @@ export class AudiobookshelfApi {
                 dispatcher: this.insecureDispatcher,
             })
             : await fetch(url, init);
-        const text = await response.text();
+        // The status decides which ceiling applies, before a byte is read. An
+        // error body is only ever quoted back after being cut to 2 000 characters,
+        // so it gets a ceiling of its own and is truncated rather than refused —
+        // that keeps the status code, which is the diagnostic, instead of
+        // replacing it with a size complaint. A successful body cannot be
+        // truncated: half a JSON document is not a smaller answer.
+        const { text, truncated } = await readCapped(response, response.ok ? MAX_RESPONSE_BYTES : MAX_ERROR_BYTES, !response.ok);
         if (!response.ok) {
             throw new AudiobookshelfApiError(response.status, text, method, path);
         }
+        if (truncated) {
+            throw new ResponseTooLargeError(path, MAX_RESPONSE_BYTES);
+        }
+        // A body-less success. Several routes answer 200 or 204 with nothing at
+        // all, and "nothing" has no content type to check.
+        if (text.length === 0)
+            return undefined;
+        // A route that is known to answer text. Its caller ignores the value.
+        if (options.text)
+            return text;
         const contentType = response.headers.get('content-type') ?? '';
-        if (contentType.includes('application/json')) {
-            try {
-                return JSON.parse(text);
-            }
-            catch {
-                return text;
-            }
+        if (!contentType.includes('application/json')) {
+            throw new UnexpectedContentTypeError(path, quoted(contentType));
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new UnexpectedContentTypeError(path, `${quoted(contentType)} (unparseable)`);
         }
-        return text;
     }
-    get(path) {
-        return this.request('GET', path);
+    get(path, options) {
+        return this.request('GET', path, undefined, options);
     }
-    post(path, body) {
-        return this.request('POST', path, body);
+    post(path, body, options) {
+        return this.request('POST', path, body, options);
     }
-    patch(path, body) {
-        return this.request('PATCH', path, body);
+    patch(path, body, options) {
+        return this.request('PATCH', path, body, options);
     }
-    delete(path) {
-        return this.request('DELETE', path);
+    delete(path, options) {
+        return this.request('DELETE', path, undefined, options);
     }
 }
 /**

package/dist/clean.d.ts

@@ -0,0 +1,123 @@
+/**
+ * What is done to text on its way out of this server.
+ *
+ * Every string an Audiobookshelf answer carries was written by somebody else:
+ * a title or a narrator's name from the file's own tags, a description from
+ * whichever metadata provider the instance queries, an episode summary from a
+ * podcast feed, a collection name from whoever shares the server. All of it
+ * goes into a model's context. Three things happen here, in one place, so no
+ * field is the one a sweep missed:
+ *
+ * - **C0 and C1 control characters and DEL are removed**, except tab, line feed
+ *   and carriage return. A terminal escape in a book title repaints the log of
+ *   whoever reads the tool result; a NUL ends the string early for whatever
+ *   parses it next. Nothing in this API means anything by them.
+ * - **Lone surrogates are repaired.** `"\ud800"` is legal JSON and parses to
+ *   half a character. `JSON.stringify` writes it back as an escape, so the wire
+ *   stays valid — and a Python client encoding the text to UTF-8 then raises
+ *   `UnicodeEncodeError: surrogates not allowed`. `toWellFormed()` replaces the
+ *   half with U+FFFD, and it runs after every cut, because a cut can split a
+ *   pair.
+ * - **Credentials in URLs are redacted.** A podcast `feedUrl` is the one field
+ *   here that routinely carries them: a private feed is published as
+ *   `https://user:token@feeds.example.com/…`, Audiobookshelf stores it as
+ *   given, and `get_library_item` hands it back.
+ *
+ * Format characters (bidi marks, joiners, zero-width) are kept. They are
+ * content in a title written in Arabic, Hebrew or Hindi, and this server's
+ * results are already framed as untrusted where it matters.
+ *
+ * The character classes are decided by code point in a loop rather than spelled
+ * as a regular expression: the editing tools of this family turn a backslash-u
+ * escape in a source line into the raw byte, and a raw escape character in this
+ * file is exactly what the file exists to keep out of a result.
+ */
+/** Whether a string carries anything {@link cleanText} would remove. */
+export declare function hasControl(value: string): boolean;
+/**
+ * Strips control characters and repairs lone surrogates.
+ *
+ * Linear, and cheap on the common case: a string with nothing to remove is
+ * returned as it came, after a well-formedness check that costs one pass.
+ */
+export declare function cleanText(value: string): string;
+/**
+ * Removes credentials from a URL.
+ *
+ * The pattern stops at the *last* `@` before the path — `[^/?#]*@` — so
+ * `https://a@b@host/` loses both, and a path or query that merely contains an
+ * `@` is left alone.
+ */
+export declare function redactUrl(url: string): string;
+/**
+ * {@link cleanText} over a whole structure, with URL redaction on the way.
+ *
+ * Rebuilds every object with `Object.fromEntries`, so a key of `__proto__` —
+ * an own property after `JSON.parse`, and legal JSON from any backend — stays
+ * an own property of the copy instead of becoming its prototype. Keys are
+ * cleaned as well as values: a key is text a model reads too.
+ *
+ * Numbers, booleans and null pass through. `undefined` and functions cannot
+ * come out of JSON; they are dropped from objects, where `JSON.stringify`
+ * would drop them anyway, and written as `null` in arrays, which is also what
+ * it would do — so the two channels cannot disagree about them.
+ */
+export declare function cleanValue(value: unknown): unknown;
+/**
+ * Text written by whatever answered a request, made safe to quote.
+ *
+ * Audiobookshelf's error bodies are short and worth reading — "Invalid
+ * playlist items. Length mismatch" is the whole diagnosis. But the thing that
+ * answers is not always Audiobookshelf: a reverse proxy, an SSO portal or an
+ * outbound filter writes its own body, and under `AUDIOBOOKSHELF_INSECURE_TLS`
+ * so can anything that can reach the address. So the text is stripped, cut and
+ * labelled as what it is.
+ */
+export declare function upstreamText(text: string, max?: number): string;
+/**
+ * A value shortened for a sentence.
+ *
+ * For the messages that have to name what was rejected — a media type that is
+ * not "book", a content type that is not JSON — without letting a hundred
+ * kilobytes of the instance's choosing into the model's context.
+ */
+export declare function quoted(value: string, max?: number): string;
+/**
+ * Refuses a header value the HTTP layer would refuse, without quoting it.
+ *
+ * undici's own refusal is `Headers.append: "<value>" is an invalid header
+ * value.` — the whole value, in a `TypeError` that this server turns into a
+ * tool result. The one header this server builds from a secret is
+ * `Authorization`, so an API key with a line break in the middle of it — a
+ * wrapped paste — would arrive in the model's context by way of an error
+ * message. Refusing first means the runtime never gets to quote one.
+ *
+ * The message names the header and where the offending character sits, which
+ * is what someone fixing a pasted credential needs, and nothing else.
+ */
+export declare function assertHeaderValue(name: string, value: string): void;
+/** Whether a field of this name holds a credential. */
+export declare function isCredentialKey(key: string): boolean;
+/** What {@link redactCredentials} put in place of a value, and where. */
+export interface RedactionReport {
+    /** Dotted paths of the fields that were replaced, in encounter order. */
+    readonly removed: string[];
+}
+/**
+ * Replaces credential-shaped fields anywhere in a record the API returned.
+ *
+ * The reason this exists at all is `GET /api/me`. It answers with
+ * `User.toOldJSONForBrowser()`, and `MeController.getCurrentUser` calls it
+ * without `hideRootToken` — so the document carries `token`, the account's old
+ * non-expiring access token, for the root user included. `detail: "full"`
+ * hands the raw record on, which put a credential that outlives this process
+ * into a model's context and into whatever that model's operator logs.
+ *
+ * Written as a walk over every pass-through record rather than as a `delete`
+ * on that one field: the projection is not the API, and the next release of
+ * either is free to add a second one.
+ */
+export declare function redactCredentials(value: unknown, report?: RedactionReport, path?: string): {
+    value: unknown;
+    report: RedactionReport;
+};