jaypost 0.0.0 → 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+//#region src/format/types.d.ts
+/** How the caller's text is read: shown as is, or as the markdown subset. */
+type MessageFormat = 'plain' | 'markdown';
+//#endregion
+//#region src/format/escape.d.ts
+/**
+ * Backslash-escapes every character the markdown subset could treat as markup, so that
+ * `format: "markdown"` shows `text` as typed. Never throws.
+ */
+export declare function escapeMarkdown(text: string): string;
+/**
+ * Wraps `code` in a fenced block that shows it verbatim, with a fence longer than any backtick
+ * run that starts a line of `code`. Throws a RangeError when `language` isn't a plain word.
+ */
+export declare function formatCodeBlock(code: string, language?: string): string;
+//#endregion
+//#region src/client/types.d.ts
+/** Where `Client` finds the service, and the project name its messages carry by default. */
+type ClientOptions = {
+  /** Default `127.0.0.1`. */
+  readonly host?: string;
+  /** Default 8787. */
+  readonly port?: number;
+  /** Shown as `[project]` on the first line of every message, unless a call sets its own. */
+  readonly project?: string;
+  /**
+   * Sent as a bearer token. Default: `JAYPOST_TOKEN`, else `~/.config/jaypost/token`,
+   * looked up on every call. Throws a `RangeError` at construction if it isn't a valid token.
+   */
+  readonly token?: string;
+};
+/**
+ * One file sent along with a message: read from `path` (named by its basename unless `name` is
+ * set), or given as `text` or `data` under a `name`. At most 10 MiB, and never empty.
+ */
+type AttachmentInput = {
+  readonly path: string;
+  readonly name?: string;
+} | {
+  readonly name: string;
+  readonly text: string;
+} | {
+  readonly name: string;
+  readonly data: Uint8Array;
+};
+/**
+ * A question answered by buttons and/or a typed reply; `timeout` in seconds, default 300, max 86400 (24 h); longer values are
+ * capped.
+ */
+type AskRequest = {
+  readonly text: string;
+  /** Button labels; required unless `allowText`. */
+  readonly options?: readonly string[];
+  /** Let the owner answer with a text reply. */
+  readonly allowText?: boolean;
+  /** Answer returned on timeout; one of `options`, or with `allowText` any short answer. */
+  readonly timeoutOption: string;
+  readonly timeout?: number;
+  readonly project?: string;
+  /** Default plain; markdown renders a subset, see the README. */
+  readonly format?: MessageFormat;
+  /** One file sent with the question. Needs a service that supports attachments. */
+  readonly attachment?: AttachmentInput;
+  /** Aborting it cancels the question; the chat message is edited to a "cancelled" line. */
+  readonly signal?: AbortSignal;
+};
+/** The tapped option or typed reply, or `timeoutOption` with `timedOut` set. */
+type Answer = {
+  readonly answer: string;
+  readonly timedOut: boolean;
+};
+/** A message that doesn't need an answer. */
+type Notification = {
+  readonly text: string;
+  readonly project?: string;
+  /** Default plain; markdown renders a subset, see the README. */
+  readonly format?: MessageFormat;
+  /** One file sent with the message. Needs a service that supports attachments. */
+  readonly attachment?: AttachmentInput;
+  readonly signal?: AbortSignal;
+};
+//#endregion
+//#region src/client/client.d.ts
+/** Thrown by `Client` when the service is unreachable, rejects the input or can't send. */
+export declare class JaypostError extends Error {
+  name: string;
+}
+/**
+ * Asks questions and sends notifications through a running jaypost service. Calls throw
+ * `JaypostError` when the token lookup finds an unusable token.
+ */
+export declare class Client {
+  #private;
+  constructor(options?: ClientOptions);
+  /**
+   * Resolves once the user taps a button or replies with text (`allowText`), or the timeout fires
+   * (then with `timeoutOption`). Throws `JaypostError` on failure (including an unusable token
+   * lookup), or the signal's reason if aborted.
+   */
+  request(request: AskRequest): Promise<Answer>;
+  /** Resolves once Telegram accepts the message. Throws like `request`. */
+  notify(notification: Notification): Promise<void>;
+}
+//#endregion
+export type { Answer, AskRequest, AttachmentInput, ClientOptions, MessageFormat, Notification };

package/dist/index.js

@@ -0,0 +1,579 @@
+import { createReadStream, readFileSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { request } from "node:http";
+import { homedir } from "node:os";
+//#region src/approval/constants.ts
+/** Hard cap on a request's timeout, in seconds (24 h); longer values are clamped. */
+const MAX_TIMEOUT_SECONDS = 86400;
+/** Largest attachment accepted by the API, in decoded bytes (10 MiB). */
+const MAX_ATTACHMENT_BYTES = 10485760;
+/** Fixed copy for failures, shown to agents and scripts as is. */
+const CANCELLED_MESSAGE = "cancelled";
+const TOO_OLD_MESSAGE = "jaypost service is too old for notifications (run jaypost init to upgrade)";
+const NOT_SUPPORTED_MESSAGE = "notifications not supported by this provider";
+const NOT_PAIRED_MESSAGE = "jaypost isn't paired yet (run jaypost status)";
+const SEND_FAILED_MESSAGE = "couldn't send the message to the user";
+/** Extra time the HTTP call gets beyond the approval timeout, so the service answers first. */
+const FETCH_GRACE_MS = 3e4;
+/** Shown when the service answers 401 and no token was sent. */
+const TOKEN_REQUIRED_MESSAGE = "jaypost service needs a token; set JAYPOST_TOKEN to the contents of ~/.config/jaypost/token on the host";
+/** Shown when the service answers 401 to a token that was sent. */
+const TOKEN_REJECTED_MESSAGE = "jaypost service rejected the token; check JAYPOST_TOKEN, or re-run jaypost init if the token file changed";
+/** Shown when a long /request timed out early, which only a service without long timeouts does. */
+const TIMEOUT_TOO_OLD_MESSAGE = "jaypost service is too old for timeouts over 300 s (run jaypost init to upgrade)";
+/** Shown when the service has no /request/async. */
+const BACKGROUND_TOO_OLD_MESSAGE = "jaypost service is too old for background questions (run jaypost init to upgrade)";
+/** Extra time a call with an attachment gets, for the upload and the service's send. */
+const ATTACHMENT_GRACE_MS = 12e4;
+/** Shown when the service's /status doesn't report an attachment limit. */
+const ATTACHMENT_TOO_OLD_MESSAGE = "jaypost service is too old for attachments (run jaypost init to upgrade)";
+/** Shown when the provider can't send attachments. */
+const ATTACHMENT_NOT_SUPPORTED_MESSAGE = "attachments not supported by this provider";
+//#endregion
+//#region src/client/http.ts
+/** POSTs JSON to the local service; see `callApi`. */
+function postApi(port, path, body, options) {
+	return callApi(port, "POST", path, body, options);
+}
+/**
+* Calls the local service with JSON (no body when `body` is undefined). 200 and 202 are ok. Never
+* throws; no retries. Uses node:http rather than fetch, whose 300 s headers timeout would cut off
+* a request that waits the full approval timeout.
+*/
+async function callApi(port, method, path, body, options) {
+	const timeout = AbortSignal.timeout(Math.ceil(options.timeoutMs));
+	const signal = AbortSignal.any([options.signal, timeout]);
+	let response;
+	try {
+		response = await send(options.host ?? "127.0.0.1", port, method, path, body === void 0 ? void 0 : JSON.stringify(body), signal, options.token);
+	} catch {
+		return {
+			kind: "failed",
+			message: describeTransportFailure(port, options, timeout)
+		};
+	}
+	if (response.status === 200 || response.status === 202) return parseOk(response.text);
+	return {
+		kind: "failed",
+		message: describeStatus(response.status, path, response.text, options.token !== void 0)
+	};
+}
+const KEEPALIVE_MS = 6e4;
+/**
+* HTTP timeout for a /request call: the capped approval timeout plus a grace period, and more
+* when the call uploads an attachment.
+*/
+function toFetchTimeoutMs(timeoutSeconds, hasAttachment = false) {
+	return Math.min(timeoutSeconds ?? 300, MAX_TIMEOUT_SECONDS) * 1e3 + toSendTimeoutMs(hasAttachment);
+}
+/** HTTP timeout for a call that returns once the message is sent (/notify, /request/async). */
+function toSendTimeoutMs(hasAttachment) {
+	return FETCH_GRACE_MS + (hasAttachment ? ATTACHMENT_GRACE_MS : 0);
+}
+/**
+* Asks a question through /request. Fails with `TIMEOUT_TOO_OLD_MESSAGE` when a request over
+* 300 s times out early, since only a service without long timeouts caps it at 300 s. Never throws.
+*/
+async function requestApi(port, body, options) {
+	const now = options.now ?? (() => performance.now());
+	const startMs = now();
+	const result = await postApi(port, "/request", body, {
+		...options,
+		timeoutMs: toFetchTimeoutMs(body.timeout, body.attachment !== void 0)
+	});
+	const elapsedMs = now() - startMs;
+	if (result.kind === "failed") return result;
+	if (!isOutcome(result.body)) return {
+		kind: "failed",
+		message: `jaypost service sent an unreadable answer: ${JSON.stringify(result.body)}`
+	};
+	const { answer, timedOut } = result.body;
+	if (timedOut && isTooEarly(body.timeout, elapsedMs)) return {
+		kind: "failed",
+		message: TIMEOUT_TOO_OLD_MESSAGE
+	};
+	return {
+		kind: "ok",
+		outcome: {
+			answer,
+			timedOut
+		}
+	};
+}
+function isTooEarly(timeoutSeconds, elapsedMs) {
+	if (timeoutSeconds === void 0 || timeoutSeconds <= 300) return false;
+	return elapsedMs < Math.min(timeoutSeconds, MAX_TIMEOUT_SECONDS) * 1e3 - FETCH_GRACE_MS;
+}
+/** Rejects on connection errors, resets and aborts; an abort destroys the socket. */
+function send(host, port, method, path, payload, signal, token) {
+	return new Promise((resolve, reject) => {
+		const request$1 = request({
+			host,
+			port,
+			path,
+			method,
+			headers: {
+				...payload === void 0 ? {} : {
+					"content-type": "application/json",
+					"content-length": Buffer.byteLength(payload)
+				},
+				...token === void 0 ? {} : { authorization: `Bearer ${token}` }
+			},
+			signal
+		}, (response) => {
+			let text = "";
+			response.setEncoding("utf8");
+			response.on("data", (chunk) => {
+				text += chunk;
+			});
+			response.on("error", reject);
+			response.on("close", () => {
+				if (!response.complete) {
+					reject(/* @__PURE__ */ new Error("response cut off"));
+					return;
+				}
+				resolve({
+					status: response.statusCode ?? 0,
+					text
+				});
+			});
+		});
+		request$1.on("socket", (socket) => {
+			socket.setKeepAlive(true, KEEPALIVE_MS);
+		});
+		request$1.on("error", reject);
+		request$1.end(payload);
+	});
+}
+function describeTransportFailure(port, options, timeout) {
+	if (options.signal.aborted) return CANCELLED_MESSAGE;
+	if (timeout.aborted) return `jaypost service didn't answer within ${options.timeoutMs / 1e3} s`;
+	return `jaypost service not reachable on ${options.host ?? "127.0.0.1"}:${port} (run jaypost status)`;
+}
+/** The copy for a 404 on a request id. */
+function describeUnknownRequest(id) {
+	return `jaypost doesn't know request ${id} (the service restarted, or the answer expired after 24 h)`;
+}
+/** True for a /request answer body: `{ answer, timedOut }`. */
+function isOutcome(body) {
+	return typeof body === "object" && body !== null && "answer" in body && typeof body.answer === "string" && "timedOut" in body && typeof body.timedOut === "boolean";
+}
+function parseOk(text) {
+	try {
+		return {
+			kind: "ok",
+			body: JSON.parse(text)
+		};
+	} catch {
+		return {
+			kind: "failed",
+			message: `jaypost service sent an unreadable answer: ${text.trim()}`
+		};
+	}
+}
+/** The 401 copy: a token was never sent, or it was sent and refused. */
+function describeUnauthorized(sentToken) {
+	return sentToken ? TOKEN_REJECTED_MESSAGE : TOKEN_REQUIRED_MESSAGE;
+}
+function describeStatus(status, path, text, sentToken) {
+	const error = readErrorField(text);
+	if (status === 401) return describeUnauthorized(sentToken);
+	if (status === 400 && error !== void 0) return error;
+	if (status === 404 && path === "/notify") return TOO_OLD_MESSAGE;
+	if (status === 404 && path === "/request/async") return BACKGROUND_TOO_OLD_MESSAGE;
+	if (status === 404 && path.startsWith("/request/")) return describeUnknownRequest(path.slice(9).split("?")[0] ?? "");
+	if (status === 501) return error === "attachments not supported" ? ATTACHMENT_NOT_SUPPORTED_MESSAGE : NOT_SUPPORTED_MESSAGE;
+	if (status === 503) return NOT_PAIRED_MESSAGE;
+	if (status === 502) return SEND_FAILED_MESSAGE;
+	return `jaypost service error ${status}: ${error ?? text.trim()}`;
+}
+function readErrorField(text) {
+	try {
+		const parsed = JSON.parse(text);
+		if (typeof parsed === "object" && parsed !== null && "error" in parsed) return typeof parsed.error === "string" ? parsed.error : void 0;
+	} catch {}
+}
+//#endregion
+//#region src/client/attachment.ts
+/**
+* Reads the attachment locally, then asks the service for its size limit, so a bad file or an
+* old or unsupporting service fails before any upload. Never throws; doesn't log names or content.
+*/
+async function prepareAttachment(port, source, options) {
+	const label = describeSource(source);
+	const read = await readSource(source, label, options.signal);
+	if (read.kind === "failed") return read;
+	const status = await callApi(port, "GET", "/status", void 0, {
+		...options,
+		timeoutMs: FETCH_GRACE_MS
+	});
+	if (status.kind === "failed") return status;
+	const limit = readLimit(status.body);
+	if (limit === void 0) return {
+		kind: "failed",
+		message: ATTACHMENT_TOO_OLD_MESSAGE
+	};
+	if (limit === 0) return {
+		kind: "failed",
+		message: ATTACHMENT_NOT_SUPPORTED_MESSAGE
+	};
+	if (read.byteLength > limit) return {
+		kind: "failed",
+		message: describeOver(label, limit)
+	};
+	return {
+		kind: "ok",
+		attachment: read.body
+	};
+}
+function describeSource(source) {
+	if ("stream" in source) return "attachment from stdin";
+	if ("path" in source) return `attachment ${JSON.stringify(source.path)}`;
+	return `attachment ${JSON.stringify(source.name)}`;
+}
+function describeOver(label, limit) {
+	return `${label} is over ${limit} bytes`;
+}
+function describeReadFailure(label, error) {
+	return `couldn't read ${label}: ${error instanceof Error ? error.message : String(error)}`;
+}
+function readLimit(body) {
+	if (typeof body === "object" && body !== null && "maxAttachmentBytes" in body) return typeof body.maxAttachmentBytes === "number" ? body.maxAttachmentBytes : void 0;
+}
+function readSource(source, label, signal) {
+	if ("stream" in source) return readStream(source.stream, source.name, label, signal);
+	if ("path" in source) return readPath(source.path, source.name, label);
+	if ("text" in source) return Promise.resolve({
+		kind: "read",
+		body: {
+			name: source.name,
+			text: source.text
+		},
+		byteLength: Buffer.byteLength(source.text)
+	});
+	return Promise.resolve({
+		kind: "read",
+		body: {
+			name: source.name,
+			data: Buffer.from(source.data).toString("base64")
+		},
+		byteLength: source.data.byteLength
+	});
+}
+async function readPath(path, name, label) {
+	const absolute = resolve(path);
+	let collected;
+	try {
+		const info = await stat(absolute);
+		if (!info.isFile()) return {
+			kind: "failed",
+			message: `${label} is not a file`
+		};
+		if (info.size > 10485760) return {
+			kind: "failed",
+			message: describeOver(label, MAX_ATTACHMENT_BYTES)
+		};
+		const file = createReadStream(absolute);
+		try {
+			collected = await collect(file);
+		} finally {
+			file.destroy();
+		}
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return {
+			kind: "failed",
+			message: `${label} not found`
+		};
+		return {
+			kind: "failed",
+			message: describeReadFailure(label, error)
+		};
+	}
+	if (collected.kind === "over") return {
+		kind: "failed",
+		message: describeOver(label, MAX_ATTACHMENT_BYTES)
+	};
+	return {
+		kind: "read",
+		body: {
+			name: name ?? basename(absolute),
+			data: Buffer.concat(collected.chunks).toString("base64")
+		},
+		byteLength: collected.byteLength
+	};
+}
+async function readStream(stream, name, label, signal) {
+	let collected;
+	try {
+		collected = await collect(stream, signal);
+	} catch (error) {
+		return {
+			kind: "failed",
+			message: describeReadFailure(label, error)
+		};
+	}
+	if (collected.kind === "over") return {
+		kind: "failed",
+		message: describeOver(label, MAX_ATTACHMENT_BYTES)
+	};
+	return {
+		kind: "read",
+		body: {
+			name,
+			data: Buffer.concat(collected.chunks).toString("base64")
+		},
+		byteLength: collected.byteLength
+	};
+}
+async function collect(source, signal) {
+	signal?.throwIfAborted();
+	const iterator = source[Symbol.asyncIterator]();
+	const aborted = new Promise((_resolve, reject) => {
+		signal?.addEventListener("abort", () => reject(signal.reason), { once: true });
+	});
+	aborted.catch(() => {});
+	const chunks = [];
+	let total = 0;
+	try {
+		for (;;) {
+			const step = await Promise.race([iterator.next(), aborted]);
+			if (step.done === true) return {
+				kind: "collected",
+				chunks,
+				byteLength: total
+			};
+			const buffer = Buffer.from(step.value);
+			total += buffer.byteLength;
+			if (total > 10485760) return { kind: "over" };
+			chunks.push(buffer);
+		}
+	} finally {
+		iterator.return?.()?.catch?.(() => {});
+	}
+}
+//#endregion
+//#region src/auth/constants.ts
+/** Env var clients and the service read the token from. */
+const TOKEN_ENV_VAR = "JAYPOST_TOKEN";
+/** Client token file name inside the config directory. */
+const TOKEN_FILE_NAME = "token";
+/** The RFC 6750 b64token alphabet, 32 to 256 characters, so `openssl rand -base64` output fits. */
+const TOKEN_PATTERN = /^[A-Za-z0-9._~+/-]{32,256}$/;
+/** Client result when no token is configured. */
+const NO_CLIENT_TOKEN = { kind: "none" };
+//#endregion
+//#region src/config/paths.ts
+/** Env value, with an empty string counting as unset. */
+function findEnvValue(env, key) {
+	const value = env[key];
+	return value === void 0 || value === "" ? void 0 : value;
+}
+/**
+* Path of config.json: $JAYPOST_CONFIG, else under $XDG_CONFIG_HOME or ~/.config. Empty env
+* values count as unset.
+*/
+function resolveConfigPath(env = process.env) {
+	const explicit = findEnvValue(env, "JAYPOST_CONFIG");
+	if (explicit) return explicit;
+	const base = findEnvValue(env, "XDG_CONFIG_HOME") ?? join(findEnvValue(env, "HOME") ?? homedir(), ".config");
+	return join(base, "jaypost", "config.json");
+}
+/** Default config directory, ignoring $JAYPOST_CONFIG; install files live here. */
+function resolveConfigDirectory(env = process.env) {
+	const { JAYPOST_CONFIG: _ignored, ...rest } = env;
+	return dirname(resolveConfigPath(rest));
+}
+//#endregion
+//#region src/system/files.ts
+/** True when `error` is a Node error with code `ENOENT`. */
+function isMissingFileError(error) {
+	return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+//#endregion
+//#region src/auth/token.ts
+/** The trimmed value when it is a valid token, else undefined. Never throws. */
+function parseToken(raw) {
+	const trimmed = raw.trim();
+	return TOKEN_PATTERN.test(trimmed) ? trimmed : void 0;
+}
+/** Path of the client token file in the install config directory; ignores JAYPOST_CONFIG. */
+function resolveTokenFile(env = process.env) {
+	return join(resolveConfigDirectory(env), TOKEN_FILE_NAME);
+}
+/** Raw text of the token file, or undefined when it is missing; other read errors are rethrown. */
+function readTokenFile(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		if (isMissingFileError(error)) return;
+		throw error;
+	}
+}
+/**
+* Finds the client token: the env var (empty counts as unset), then the file, else none. A source
+* that exists but is invalid or unreadable gives `unusable`, with a message that names the source
+* and never the value. Never throws.
+*/
+function resolveClientToken(env, tokenFile) {
+	const fromEnv = findEnvValue(env, TOKEN_ENV_VAR);
+	if (fromEnv !== void 0) {
+		const token = parseToken(fromEnv);
+		return token === void 0 ? {
+			kind: "unusable",
+			message: `${TOKEN_ENV_VAR} isn't a valid jaypost token`
+		} : {
+			kind: "token",
+			token,
+			source: "env"
+		};
+	}
+	let raw;
+	try {
+		raw = readTokenFile(tokenFile);
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		return {
+			kind: "unusable",
+			message: `token file ${JSON.stringify(tokenFile)} couldn't be read: ${reason}`
+		};
+	}
+	if (raw === void 0) return NO_CLIENT_TOKEN;
+	const token = parseToken(raw);
+	return token === void 0 ? {
+		kind: "unusable",
+		message: `token file ${JSON.stringify(tokenFile)} isn't a valid jaypost token`
+	} : {
+		kind: "token",
+		token,
+		source: "file"
+	};
+}
+//#endregion
+//#region src/client/client.ts
+/** Thrown by `Client` when the service is unreachable, rejects the input or can't send. */
+var JaypostError = class extends Error {
+	name = "JaypostError";
+};
+/**
+* Asks questions and sends notifications through a running jaypost service. Calls throw
+* `JaypostError` when the token lookup finds an unusable token.
+*/
+var Client = class {
+	#host;
+	#port;
+	#project;
+	#token;
+	constructor(options = {}) {
+		this.#host = options.host ?? "127.0.0.1";
+		this.#port = options.port ?? 8787;
+		this.#project = options.project;
+		if (options.token !== void 0) {
+			const token = parseToken(options.token);
+			if (token === void 0) throw new RangeError("token isn't a valid jaypost token");
+			this.#token = token;
+		}
+	}
+	/**
+	* Resolves once the user taps a button or replies with text (`allowText`), or the timeout fires
+	* (then with `timeoutOption`). Throws `JaypostError` on failure (including an unusable token
+	* lookup), or the signal's reason if aborted.
+	*/
+	async request(request) {
+		const project = request.project ?? this.#project;
+		const signal = request.signal ?? new AbortController().signal;
+		const token = this.#resolveToken();
+		const attachment = await this.#prepare(request.attachment, signal, token);
+		const result = await requestApi(this.#port, {
+			text: request.text,
+			...request.options === void 0 ? {} : { options: request.options },
+			...request.allowText === void 0 ? {} : { allowText: request.allowText },
+			timeoutOption: request.timeoutOption,
+			...request.timeout === void 0 ? {} : { timeout: request.timeout },
+			...project === void 0 ? {} : { project },
+			...request.format === void 0 ? {} : { format: request.format },
+			...attachment === void 0 ? {} : { attachment }
+		}, {
+			signal,
+			host: this.#host,
+			...token === void 0 ? {} : { token }
+		});
+		if (signal.aborted) throw signal.reason;
+		if (result.kind === "failed") throw new JaypostError(result.message);
+		return result.outcome;
+	}
+	/** Resolves once Telegram accepts the message. Throws like `request`. */
+	async notify(notification) {
+		const attachment = await this.#prepare(notification.attachment, notification.signal ?? new AbortController().signal, this.#resolveToken());
+		await this.#post("/notify", {
+			text: notification.text,
+			...notification.format === void 0 ? {} : { format: notification.format },
+			...attachment === void 0 ? {} : { attachment }
+		}, notification, toSendTimeoutMs(attachment !== void 0));
+	}
+	/** Reads and checks the attachment, if any; throws `JaypostError` when it can't be sent. */
+	async #prepare(input, signal, token) {
+		if (input === void 0) return;
+		const result = await prepareAttachment(this.#port, input, {
+			signal,
+			host: this.#host,
+			...token === void 0 ? {} : { token }
+		});
+		if (signal.aborted) throw signal.reason;
+		if (result.kind === "failed") throw new JaypostError(result.message);
+		return result.attachment;
+	}
+	async #post(path, body, call, timeoutMs) {
+		const project = call.project ?? this.#project;
+		const signal = call.signal ?? new AbortController().signal;
+		const token = this.#resolveToken();
+		const result = await postApi(this.#port, path, {
+			...body,
+			...project === void 0 ? {} : { project }
+		}, {
+			signal,
+			timeoutMs,
+			host: this.#host,
+			...token === void 0 ? {} : { token }
+		});
+		if (signal.aborted) throw signal.reason;
+		if (result.kind === "failed") throw new JaypostError(result.message);
+		return result.body;
+	}
+	#resolveToken() {
+		if (this.#token !== void 0) return this.#token;
+		const found = resolveClientToken(process.env, resolveTokenFile(process.env));
+		switch (found.kind) {
+			case "token": return found.token;
+			case "none": return;
+			case "unusable": throw new JaypostError(found.message);
+		}
+	}
+};
+//#endregion
+//#region src/format/constants.ts
+/** A fenced block's language is kept only when its first info word looks like this. */
+const LANGUAGE_PATTERN = /^[A-Za-z0-9_+#.-]{1,32}$/;
+//#endregion
+//#region src/format/escape.ts
+const MARKUP_PATTERN = /[\\`*~#>]/g;
+const FENCE_RUN_PATTERN = /^ {0,3}(`+)/gm;
+/**
+* Backslash-escapes every character the markdown subset could treat as markup, so that
+* `format: "markdown"` shows `text` as typed. Never throws.
+*/
+function escapeMarkdown(text) {
+	return text.replace(MARKUP_PATTERN, "\\$&");
+}
+/**
+* Wraps `code` in a fenced block that shows it verbatim, with a fence longer than any backtick
+* run that starts a line of `code`. Throws a RangeError when `language` isn't a plain word.
+*/
+function formatCodeBlock(code, language) {
+	if (language !== void 0 && !LANGUAGE_PATTERN.test(language)) throw new RangeError(`language ${JSON.stringify(language)} must match ${LANGUAGE_PATTERN.source}`);
+	const longestRun = [...code.matchAll(FENCE_RUN_PATTERN)].reduce((longest, match) => Math.max(longest, match[1]?.length ?? 0), 0);
+	const fence = "`".repeat(Math.max(3, longestRun + 1));
+	return `${fence}${language ?? ""}\n${code}\n${fence}`;
+}
+//#endregion
+export { Client, JaypostError, escapeMarkdown, formatCodeBlock };