healthchecks-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Willi Thiel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,244 @@
+# healthchecks-mcp
+
+[![CI](https://img.shields.io/github/actions/workflow/status/ni-c/healthchecks-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/healthchecks-mcp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/healthchecks-mcp)](https://www.npmjs.com/package/healthchecks-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/healthchecks-mcp)](https://www.npmjs.com/package/healthchecks-mcp)
+[![node](https://img.shields.io/node/v/healthchecks-mcp)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/healthchecks-mcp)](LICENSE)
+[![container](https://img.shields.io/badge/ghcr.io-ni--c%2Fhealthchecks--mcp-blue)](https://github.com/ni-c/healthchecks-mcp/pkgs/container/healthchecks-mcp)
+[![docs](https://img.shields.io/badge/docs-healthchecks--mcp.ni--c.de-informational)](https://healthchecks-mcp.ni-c.de)
+[![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)
+
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for
+[Healthchecks](https://healthchecks.io), the dead man's switch for cron jobs and
+scheduled tasks — it alerts you when a job stops checking in. Works against the
+hosted service and against a self-hosted instance alike.
+
+Lets MCP clients like Claude Code, Claude Desktop or Codex see which scheduled
+jobs are healthy, read the output the failing one reported, and create or adjust
+checks — with the irreversible operations behind a confirmation token and the
+write tools switchable off entirely.
+
+Fourteen tools is the ceiling, not the floor:
+`HEALTHCHECKS_ALLOW_TOOLS=essential` registers a curated seven instead, and a
+model picks the right tool far more reliably from seven than from fourteen — see
+[choosing which tools load](#choosing-which-tools-load).
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://healthchecks-mcp.ni-c.de/architecture-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="https://healthchecks-mcp.ni-c.de/architecture-light.svg">
+  <img src="https://healthchecks-mcp.ni-c.de/architecture.svg" alt="An MCP client talks to healthchecks-mcp over stdio; the server calls the Healthchecks Management API v3 over HTTPS." width="800">
+</picture>
+
+![Listing the tools, narrowing them to the essential preset, and the startup abort a mistyped tool name produces](https://healthchecks-mcp.ni-c.de/demo.gif)
+
+## What makes it different
+
+**It reads the ping bodies.** `get_ping_body` returns what a job actually printed
+when it reported failure. Every other question — which check is down, since when,
+how often — is one step away from that one, and it is the endpoint the other
+Healthchecks MCP servers leave out.
+
+**Read-only API keys work properly.** Healthchecks hands a read-only key a
+different object: no `uuid`, no `ping_url`, no `channels` — a 40-character
+`unique_key` instead. This server addresses checks by either, and
+`get_api_key_info` tells you up front which kind of key you configured and which
+tools it cannot reach, rather than leaving you with a `401 missing api key` for a
+key that was sent.
+
+**It never pings a check.** Pinging is how a job reports that it ran. A tool that
+could ping would let a model make a dead job look alive, which is the one thing
+monitoring must not allow — see [Not exposed, on purpose](#not-exposed-on-purpose).
+
+**It knows where this API is sharp.** `timeout` and `schedule` cannot be combined
+because the upstream silently discards one of them; tags are validated against
+their space separator and keywords against their comma; a new check is given
+every integration unless you say otherwise, because the API's own default is a
+check that alerts nobody.
+
+## Requirements
+
+- Node.js ≥ 22
+- A **Healthchecks** project API key — Project Settings → API Access. Keys are per
+  project, not per account, and are exactly 32 characters long.
+
+## Configuration
+
+| Variable                    | Required | Description                                                                                           |
+| --------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
+| `HEALTHCHECKS_API_KEY`      | yes      | Project API key. A read-only key works for part of the tool surface — see below                       |
+| `HEALTHCHECKS_URL`          | no       | Site root of a self-hosted instance, e.g. `https://hc.example.net`. Default `https://healthchecks.io` |
+| `HEALTHCHECKS_READ_ONLY`    | no       | `true` registers only the read tools                                                                  |
+| `HEALTHCHECKS_ALLOW_TOOLS`  | no       | Comma-separated tool names, `list_*` prefixes, or `essential` for a curated preset                    |
+| `HEALTHCHECKS_DENY_TOOLS`   | no       | Same syntax; removed from whatever `HEALTHCHECKS_ALLOW_TOOLS` left                                    |
+| `HEALTHCHECKS_INSECURE_TLS` | no       | `true` accepts self-signed certificates (scoped to this connection)                                   |
+
+`HEALTHCHECKS_URL` is the site root, not the API root: `https://hc.example.net`,
+not `https://hc.example.net/api/v3`. Both are accepted — the suffix is trimmed —
+because the API documentation spells every example the long way.
+
+> **Use `https://`.** Over plain http the API key travels unencrypted; the server
+> prints a warning unless the host is local. For self-signed certificates prefer a
+> proper internal CA over `HEALTHCHECKS_INSECURE_TLS`.
+
+Without an API key the server still starts and lists its tools (so registries and
+inspectors can introspect it), but every call except `get_status` fails with setup
+instructions instead of reaching the API.
+
+**Read-only keys.** Healthchecks gates three tools that only read — `list_pings`,
+`get_ping_body` and `list_integrations` — behind a read-write key anyway. With a
+read-only key those fail, along with all five write tools.
+
+The failure does not look like a permission problem: the API answers
+`401 {"error": "wrong api key"}`, which reads as if the key were wrong or
+missing. It is not — those three tools translate it into what actually happened.
+`get_api_key_info` reports which kind of key is configured, and
+`HEALTHCHECKS_DENY_TOOLS` is the tidy way to stop offering them at all.
+
+### Choosing which tools load
+
+`HEALTHCHECKS_ALLOW_TOOLS` and `HEALTHCHECKS_DENY_TOOLS` take comma-separated tool
+names; a trailing `*` matches a whole family. `essential` is a curated preset —
+`list_checks`, `get_check`, `list_pings`, `list_flips`, `create_check`,
+`update_check` and `resume_check` — marked as such in the
+[tool reference](https://healthchecks-mcp.ni-c.de/reference/tools).
+
+```sh
+HEALTHCHECKS_ALLOW_TOOLS=essential
+HEALTHCHECKS_ALLOW_TOOLS=list_*,get_check
+HEALTHCHECKS_DENY_TOOLS=delete_check,pause_check
+```
+
+An entry that matches no tool aborts startup and names it, so a typo cannot silently
+hide a tool — an absent tool is not something anyone traces back to an environment
+variable. A filtered tool is never registered, so it is absent from `tools/list` and
+unknown to `tools/call` alike, exactly like a write tool under
+`HEALTHCHECKS_READ_ONLY`.
+
+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.
+
+## Installation
+
+### Claude Code
+
+```sh
+claude mcp add healthchecks-mcp -- npx -y healthchecks-mcp
+```
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "healthchecks-mcp": {
+      "command": "npx",
+      "args": ["-y", "healthchecks-mcp"],
+      "env": {
+        "HEALTHCHECKS_API_KEY": "…"
+      }
+    }
+  }
+}
+```
+
+### Codex
+
+```toml
+[mcp_servers.healthchecks-mcp]
+command = "npx"
+args = ["-y", "healthchecks-mcp"]
+env = { HEALTHCHECKS_API_KEY = "…" }
+```
+
+### Docker
+
+```sh
+docker run --rm -i \
+  -e HEALTHCHECKS_API_KEY=… \
+  ghcr.io/ni-c/healthchecks-mcp
+```
+
+Add `-e HEALTHCHECKS_URL=https://hc.example.net` for a self-hosted instance.
+
+## Tools
+
+Read tools are always registered. 🔑 marks the ones Healthchecks requires a
+read-write key for even though they only read; 👤 marks the ones that ask for a
+confirmation token before acting.
+
+| Tool                   | Description                                                    |
+| ---------------------- | -------------------------------------------------------------- |
+| `list_checks`          | Checks in the project, with `tag`, `slug` and `status` filters |
+| `get_check`            | One check with every field, by UUID or `unique_key`            |
+| `list_pings` 🔑        | Recent pings of a check, newest first                          |
+| `get_ping_body` 🔑     | The body a job POSTed with one ping — its output               |
+| `list_flips`           | Up/down transitions of a check, with a time window             |
+| `list_integrations` 🔑 | Notification integrations and the UUIDs the write tools accept |
+| `list_badges`          | Status badge URLs, per tag and for the project                 |
+| `get_status`           | Whether the instance is reachable — needs no API key at all    |
+| `get_api_key_info`     | Which instance, which kind of key, and what that key cannot do |
+
+Write tools are registered unless `HEALTHCHECKS_READ_ONLY=true`.
+
+| Tool              | Description                                                                                               |
+| ----------------- | --------------------------------------------------------------------------------------------------------- |
+| `create_check`    | Creates a check. Notifies every integration unless `channels` says otherwise                              |
+| `update_check`    | Changes the given fields. `channels` replaces the list rather than adding to it; an empty list is refused |
+| `pause_check` 👤  | Stops the check expecting pings — and alerting                                                            |
+| `resume_check`    | Puts a paused check back into the `new` state                                                             |
+| `delete_check` 👤 | Deletes a check. The UUID is not recoverable                                                              |
+
+## Not exposed, on purpose
+
+- **Pinging.** The server never calls a ping URL. Pinging is how a job says it
+  ran; a tool that could ping would let a model — or text a model read — report
+  success for a job that never executed, and a monitoring system that can be
+  talked into a green status is worse than none.
+- **Ping keys.** They are not readable through the Management API, and this server
+  does not ask for one.
+- **Creating integrations.** The API has no endpoint for it; they are configured
+  in the web UI. `list_integrations` reads them.
+- **The `unique` upsert as a default.** `create_check` accepts it and says loudly
+  in its result when it was used, because it turns a create into a silent update
+  of a check that already exists.
+
+## Safety
+
+- **`pause_check` and `delete_check` are two-step.** The first call returns a
+  short-lived confirmation token bound to that exact check and that exact
+  operation; only a second call carrying that token acts. A model cannot satisfy
+  this gate on its own, and a pause token is not a delete token.
+- **Confirmation prompts never quote content from Healthchecks** — a check's name
+  and description are free text this server does not control, and that text is
+  read by a model.
+- **Ping bodies and check descriptions are marked as untrusted data**, because
+  anything that can ping a check can write into them.
+- Error bodies are truncated, HTML error pages are dropped, and every response has
+  a byte ceiling enforced while it streams — the Management API paginates nothing.
+- `HEALTHCHECKS_READ_ONLY=true` does not register the write tools at all, and
+  `HEALTHCHECKS_DENY_TOOLS` cuts finer along the same line — a filtered tool is
+  never built, not refused at call time.
+- The API key is deleted from `process.env` once it has been read, and never
+  travels in a request body.
+
+## Development
+
+```sh
+npm install
+npm run lint && npm run build && npm run test:coverage
+```
+
+## Releasing
+
+1. Add the CHANGELOG entry and bump `package.json`.
+2. `npm run lint && npm run build && npm run test:coverage`
+3. Commit, then push a signed tag: `git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin main vX.Y.Z`
+
+The release workflow publishes to npm (Trusted Publishing, with provenance), creates
+the GitHub release from the CHANGELOG section and updates the MCP Registry entry.
+
+## License
+
+MIT © Willi Thiel

package/dist/api.d.ts

@@ -0,0 +1,86 @@
+import { type Config } from './config.js';
+/**
+ * Ceiling on a single upstream response.
+ *
+ * `GET /checks/` has no pagination at all and returns every check in the
+ * project, so the size of the answer is decided by the instance, not by us.
+ * `await response.text()` would buffer whatever arrives; this bounds it before
+ * the bytes are ever in memory as a string.
+ */
+export declare const MAX_RESPONSE_BYTES: number;
+/** The API version this server speaks. v3 is the first one that accepts an explicit slug. */
+export declare const API_VERSION = "v3";
+export declare class HealthchecksApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string, method: string, path: string);
+}
+/**
+ * Thrown when a response is larger than the ceiling that applied to it.
+ *
+ * The limit is a parameter rather than {@link MAX_RESPONSE_BYTES}, because
+ * callers override it — 64 KB for a ping body, 4 KB for the status probe — and
+ * an error announcing "exceeds 5 MB" for a 6 KB response is one nobody believes.
+ */
+export declare class ResponseTooLargeError extends Error {
+    constructor(path: string, limit: number);
+}
+/**
+ * Thrown when an endpoint that only reads was refused for needing a read-write key.
+ *
+ * Healthchecks gates `/channels/`, `/pings/` and `/pings/<n>/body` behind
+ * `@authorize` even though all three are GETs, and refuses a read-only key there
+ * with `401 {"error": "wrong api key"}`. Relaying that verbatim sends the reader
+ * to re-check a key that is correct — so the three call sites translate it.
+ */
+export declare class ReadWriteKeyRequiredError extends Error {
+    readonly tool: string;
+    constructor(tool: string);
+}
+/** Thrown when a response that has to be JSON is not. */
+export declare class UnexpectedContentTypeError extends Error {
+    constructor(path: string, contentType: string);
+}
+export interface RequestOptions {
+    /** Send no `X-Api-Key` header. Only `/status/`, which is unauthenticated. */
+    anonymous?: boolean;
+    /** Return the raw body instead of parsing it. `/pings/<n>/body` is text/plain. */
+    raw?: boolean;
+    /** Overrides {@link MAX_RESPONSE_BYTES} for endpoints with a known small ceiling. */
+    maxBytes?: number;
+}
+export interface RawResponse {
+    body: string;
+    truncated: boolean;
+    contentType: string;
+}
+/** Client for the Healthchecks Management API. */
+export declare class HealthchecksApi {
+    private readonly config;
+    private readonly baseUrl;
+    /**
+     * Only set when HEALTHCHECKS_INSECURE_TLS is enabled. Scopes the relaxed
+     * certificate validation to requests against the configured host instead of
+     * disabling it process-wide via NODE_TLS_REJECT_UNAUTHORIZED.
+     */
+    private readonly insecureDispatcher?;
+    constructor(config: Config);
+    /** The configured site root, for messages that need to name the instance. */
+    get siteRoot(): string;
+    get apiKey(): string | undefined;
+    requestRaw(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<RawResponse>;
+    request(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<unknown>;
+    get(path: string, options?: RequestOptions): Promise<unknown>;
+    post(path: string, body?: unknown): Promise<unknown>;
+    delete(path: string): Promise<unknown>;
+}
+/**
+ * Guards a value that ends up in a URL path. Path traversal here would let a
+ * caller reach a different resource — or a different API entirely.
+ *
+ * Defence in depth: every caller already validated the value against a UUID or
+ * SHA1 schema, and this catches the one that some day will not.
+ */
+export declare function assertPathSegment(value: string, what: string): string;
+/** Builds a query string from the parameters that are actually set. */
+export declare function query(params: Record<string, string | number | undefined | (string | number)[]>): string;

package/dist/api.js

@@ -0,0 +1,258 @@
+import { Agent, fetch as undiciFetch, } from 'undici';
+import { malformedApiKeyMessage, missingConfigKeys, missingConfigMessage, } from './config.js';
+const REQUEST_TIMEOUT_MS = 15_000;
+/**
+ * Ceiling on a single upstream response.
+ *
+ * `GET /checks/` has no pagination at all and returns every check in the
+ * project, so the size of the answer is decided by the instance, not by us.
+ * `await response.text()` would buffer whatever arrives; this bounds it before
+ * the bytes are ever in memory as a string.
+ */
+export const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+/** The API version this server speaks. v3 is the first one that accepts an explicit slug. */
+export const API_VERSION = 'v3';
+export class HealthchecksApiError extends Error {
+    status;
+    body;
+    constructor(status, body, method, path) {
+        super(`Healthchecks API ${method} ${path} failed with HTTP ${status}`);
+        this.status = status;
+        this.body = body;
+        this.name = 'HealthchecksApiError';
+    }
+}
+/**
+ * Thrown when a response is larger than the ceiling that applied to it.
+ *
+ * The limit is a parameter rather than {@link MAX_RESPONSE_BYTES}, because
+ * callers override it — 64 KB for a ping body, 4 KB for the status probe — and
+ * an error announcing "exceeds 5 MB" for a 6 KB response is one nobody believes.
+ */
+export class ResponseTooLargeError extends Error {
+    constructor(path, limit) {
+        super(`the Healthchecks response for ${path} exceeds the ${formatLimit(limit)} ` +
+            'ceiling and was not read.');
+        this.name = 'ResponseTooLargeError';
+    }
+}
+function formatLimit(bytes) {
+    return bytes >= 1024 * 1024
+        ? `${Math.round(bytes / 1024 / 1024)} MB`
+        : `${Math.round(bytes / 1024)} KB`;
+}
+/**
+ * Thrown when an endpoint that only reads was refused for needing a read-write key.
+ *
+ * Healthchecks gates `/channels/`, `/pings/` and `/pings/<n>/body` behind
+ * `@authorize` even though all three are GETs, and refuses a read-only key there
+ * with `401 {"error": "wrong api key"}`. Relaying that verbatim sends the reader
+ * to re-check a key that is correct — so the three call sites translate it.
+ */
+export class ReadWriteKeyRequiredError extends Error {
+    tool;
+    constructor(tool) {
+        super(`${tool} needs a read-write Healthchecks API key. The configured key was ` +
+            'rejected with HTTP 401 "wrong api key", which is how Healthchecks ' +
+            'answers a read-only key on this endpoint — it only reads, but the API ' +
+            'gates it behind a read-write key anyway. Nothing is wrong with the key ' +
+            'itself. Use a read-write key from Project Settings → API Access, or ' +
+            `HEALTHCHECKS_DENY_TOOLS=${tool} to stop offering the tool. ` +
+            'get_api_key_info reports which kind of key is configured.');
+        this.tool = tool;
+        this.name = 'ReadWriteKeyRequiredError';
+    }
+}
+/** Thrown when a response that has to be JSON is not. */
+export class UnexpectedContentTypeError extends Error {
+    constructor(path, contentType) {
+        super(`Healthchecks 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 HEALTHCHECKS_URL and try get_status.');
+        this.name = 'UnexpectedContentTypeError';
+    }
+}
+/** Client for the Healthchecks Management API. */
+export class HealthchecksApi {
+    config;
+    baseUrl;
+    /**
+     * Only set when HEALTHCHECKS_INSECURE_TLS is enabled. Scopes the relaxed
+     * certificate validation to requests against the configured host instead of
+     * disabling it process-wide via NODE_TLS_REJECT_UNAUTHORIZED.
+     */
+    insecureDispatcher;
+    constructor(config) {
+        this.config = config;
+        this.baseUrl = `${config.url}/api/${API_VERSION}`;
+        if (config.insecureTls) {
+            this.insecureDispatcher = new Agent({
+                connect: { rejectUnauthorized: false },
+            });
+        }
+    }
+    /** The configured site root, for messages that need to name the instance. */
+    get siteRoot() {
+        return this.config.url;
+    }
+    get apiKey() {
+        return this.config.apiKey;
+    }
+    async requestRaw(method, path, body, options = {}) {
+        // The key is only required here, not at startup, so the server can still be
+        // started and introspected without one.
+        if (!options.anonymous) {
+            const missing = missingConfigKeys(this.config);
+            if (missing.length > 0)
+                throw new Error(missingConfigMessage(missing));
+            const malformed = malformedApiKeyMessage(this.config);
+            if (malformed)
+                throw new Error(malformed);
+        }
+        const headers = { Accept: '*/*' };
+        if (!options.anonymous && this.config.apiKey) {
+            // The header, never the `api_key` body field the API also accepts: a body
+            // field ends up in request logs, and it only works for POST anyway.
+            headers['X-Api-Key'] = this.config.apiKey;
+        }
+        const init = {
+            method,
+            headers,
+            // Never follow a redirect: it would resend the API key to whatever host
+            // the upstream points at.
+            redirect: 'error',
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        };
+        if (body !== undefined) {
+            // The API rejects multipart and form encoding outright; every POST is
+            // JSON, including the empty-bodied pause and resume calls.
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(body);
+        }
+        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.
+        const response = this.insecureDispatcher
+            ? await undiciFetch(url, {
+                ...init,
+                dispatcher: this.insecureDispatcher,
+            })
+            : await fetch(url, init);
+        const limit = options.maxBytes ?? MAX_RESPONSE_BYTES;
+        // A raw caller wants text and can live with less of it; a JSON caller
+        // cannot, because half a document is not a smaller answer.
+        const { text, truncated } = await readCapped(response, limit, path, options.raw === true);
+        if (!response.ok) {
+            throw new HealthchecksApiError(response.status, text, method, path);
+        }
+        if (truncated && !options.raw) {
+            throw new ResponseTooLargeError(path, limit);
+        }
+        return {
+            body: text,
+            truncated,
+            contentType: response.headers.get('content-type') ?? '',
+        };
+    }
+    async request(method, path, body, options = {}) {
+        const raw = await this.requestRaw(method, path, body, options);
+        if (options.raw)
+            return raw;
+        if (raw.body.length === 0)
+            return undefined;
+        // Anything that is not JSON here is a foreign answer, not a Healthchecks
+        // one. Returning the body would send an HTML login page into `listOf`,
+        // which finds no array and reports an empty project — an error swallowed
+        // and replaced with a plausible wrong answer. The endpoints that do speak
+        // text (`/status/`, ping bodies) ask for `raw` and never reach this.
+        if (!raw.contentType.includes('application/json')) {
+            throw new UnexpectedContentTypeError(path, raw.contentType);
+        }
+        try {
+            return JSON.parse(raw.body);
+        }
+        catch {
+            throw new UnexpectedContentTypeError(path, `${raw.contentType} (unparseable)`);
+        }
+    }
+    get(path, options) {
+        return this.request('GET', path, undefined, options);
+    }
+    post(path, body) {
+        return this.request('POST', path, body);
+    }
+    delete(path) {
+        return this.request('DELETE', path);
+    }
+}
+/**
+ * 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, path, 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();
+        throw new ResponseTooLargeError(path, maxBytes);
+    }
+    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();
+            // NOTE: `total` is deliberately left stale here — the loop exits on the
+            // next line and nothing reads it afterwards. Anything added below this
+            // point must recompute it from `chunks` rather than trusting it.
+            break;
+        }
+        chunks.push(value);
+        total += value.byteLength;
+    }
+    return { text: Buffer.concat(chunks).toString('utf8'), truncated };
+}
+/**
+ * Guards a value that ends up in a URL path. Path traversal here would let a
+ * caller reach a different resource — or a different API entirely.
+ *
+ * Defence in depth: every caller already validated the value against a UUID or
+ * SHA1 schema, and this catches the one that some day will not.
+ */
+export function assertPathSegment(value, what) {
+    if (!/^[A-Za-z0-9._-]+$/.test(value) || value === '.' || value === '..') {
+        throw new Error(`invalid ${what}: only letters, digits, dot, underscore and hyphen are allowed`);
+    }
+    return value;
+}
+/** Builds a query string from the parameters that are actually set. */
+export function query(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined)
+            continue;
+        for (const entry of Array.isArray(value) ? value : [value]) {
+            search.append(key, String(entry));
+        }
+    }
+    const rendered = search.toString();
+    return rendered ? `?${rendered}` : '';
+}
+//# sourceMappingURL=api.js.map

package/dist/check.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Shaping of the API's check objects.
+ *
+ * Three things need doing before a check is worth handing to a model, and all
+ * three are properties of the API rather than preferences:
+ *
+ * 1. There is no `kind` field. Whether a check is a simple timeout or a
+ *    scheduled one has to be inferred from which of `timeout` / `schedule` is
+ *    present, and a reader who does not know that reads a missing `timeout` as
+ *    a missing value.
+ * 2. The identifier is `uuid` for a read-write key and `unique_key` for a
+ *    read-only one — never both, and the difference is invisible in the object.
+ * 3. `subject` and `subject_fail` are legacy derived duplicates of
+ *    `success_kw` / `failure_kw`; they are not writable and having them in the
+ *    output invites an update that silently does nothing.
+ */
+export interface Check {
+    [key: string]: unknown;
+    uuid?: string;
+    unique_key?: string;
+    name?: string;
+    slug?: string;
+    tags?: string;
+    status?: string;
+    timeout?: number;
+    schedule?: string;
+    tz?: string;
+}
+/** The identifier this object can actually be addressed by, whichever it carries. */
+export declare function checkIdOf(check: Check): string | undefined;
+/**
+ * Splits the space-delimited `tags` string into a list.
+ *
+ * Space-delimited is why `tagParam` refuses a tag containing a space: the round
+ * trip through this function would turn one tag into two.
+ */
+export declare function tagsOf(check: Check): string[];
+/** `simple` when the check is driven by `timeout`, `scheduled` when by `schedule`. */
+export declare function scheduleKindOf(check: Check): 'simple' | 'scheduled';
+/** Normalizes one check without dropping anything a caller might need. */
+export declare function normalizeCheck(check: Check): Record<string, unknown>;
+/**
+ * The compact projection used in list results.
+ *
+ * `desc` is deliberately absent: it is free text of up to ten thousand
+ * characters and a list of two hundred checks would be mostly descriptions.
+ * `get_check` returns it.
+ */
+export declare function summarizeCheck(check: Check): Record<string, unknown>;
+/**
+ * Reads the flips out of a response.
+ *
+ * The published documentation shows a bare array while the implementation
+ * returns `{"flips": [...]}`; both spellings are in the wild, since a
+ * self-hosted instance can be any release. Accepting both is one line and
+ * removes a whole class of "it works against my instance" bug report.
+ */
+export declare function flipsOf(body: unknown): unknown[];
+/** Reads a `{"<key>": [...]}` envelope, tolerating a bare array. */
+export declare function listOf(body: unknown, key: string): unknown[];