@mycroblog/mykit 0.0.0-placeholder.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The mycroblog/my contributors
+
+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,129 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# @mycroblog/mykit
+
+The TypeScript client of the client API of [my](https://github.com/mycroblog/my), an ActivityPub microblog server.
+It is [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) typed by the server's OpenAPI spec, plus what every call
+needs: the access token and its renewal, `Accept-Language`, errors, paging, retries, idempotency keys, media upload,
+PKCE, and the event stream. It is ESM only and runs wherever `fetch` and web streams do (Node.js 22 or later, Bun,
+Deno, browsers); it imports no Node.js built-in module.
+
+The Go client has the same behavior; the full guide, which applies to both, is the [mykit README](../README.md). This
+page has the TypeScript parts.
+
+> **Mastodon client libraries do not work with my.** The client API is not Mastodon's (there is no `/api/v1/apps`).
+> Register an OAuth 2.0 client instead; see [Getting a token](../README.md#getting-a-token).
+
+```sh
+npm install @mycroblog/mykit
+```
+
+## Quick start
+
+The runnable-by-type-check versions of these snippets are in [`examples/`](examples).
+
+```ts
+import { createClient, NetworkError, ProblemError, staticToken } from "@mycroblog/mykit";
+
+const api = createClient({
+  server: "https://example.com", // the origin, without a path
+  tokenSource: staticToken("access token"),
+  acceptLanguage: "en",
+});
+
+const { data } = await api.POST("/statuses", { body: { text: "Hello, fediverse!", visibility: "public" } });
+console.log(data?.id);
+```
+
+`api` is an openapi-fetch client: `api.GET`, `api.POST`, and so on take the path of the operation, and the parameters,
+the body, and `data` are typed by the spec. A call that gets an answer of 400 or more **rejects** with a `ProblemError`
+(openapi-fetch's `error` field is not used), so when it resolves, `data` is the answer.
+
+## Errors
+
+```ts
+try {
+  await api.POST("/statuses", { body: { text: "hi", visibility: "public" } });
+} catch (error) {
+  if (error instanceof ProblemError && error.type === "/api/v1/problems/blocking") {
+    // ...
+  } else if (error instanceof NetworkError) {
+    // no answer; error.cause is the error of fetch
+  }
+}
+```
+
+`ProblemError` is an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem: `type`, `title`, `status`, `detail`,
+the extension members in `problem`, and the response `headers`. **Branch on `type` and `status`, never on `title` or
+`detail`**, which the server localizes from `Accept-Language`. An aborted request rejects with the reason of its signal.
+
+Middleware of your own that turns an error answer into an error type of yours before the `ProblemError` can read the
+problem with `problemFromResponse(response)`.
+
+## Getting a token and saving it
+
+mykit never stores tokens. The flow with PKCE, and a `RefreshingTokenSource` whose `onTokens` callback saves the
+rotated refresh token, are in [`examples/oauth.ts`](examples/oauth.ts):
+
+```ts
+const token = await exchange(oauth, code, verifier);
+const api = createClient({
+  server: oauth.server,
+  tokenSource: new RefreshingTokenSource(oauth, token, async (renewed) => {
+    await save(renewed); // your own storage
+  }),
+});
+```
+
+The server rotates the refresh token on every use, and a refresh token used twice revokes the whole token family, so
+`onTokens` must save the new tokens. The source renews the token when it expires or after a 401, once per request.
+
+A `TokenSource` is any object with `getAccessToken()` and, optionally, `refresh(refused)`.
+
+## Paging
+
+```ts
+for await (const status of all(async (cursor) => {
+  const { data } = await api.GET("/timelines/home", { params: { query: cursor === undefined ? {} : { cursor } } });
+  if (data === undefined) throw new Error("the answer has no body");
+  return data;
+})) {
+  console.log(status.id);
+  if (done()) break; // a timeline has no end
+}
+```
+
+## Streaming
+
+```ts
+const controller = new AbortController();
+await runStream({
+  server: "https://example.com",
+  tokenSource,
+  signal: controller.signal,
+  onOpen: (reconnected) => {
+    if (reconnected) refetchTimelinesAndNotifications();
+  },
+  onEvent: (event) => {
+    if (event.type === "update") console.log(event.status.id);
+  },
+});
+```
+
+`runStream` connects again whenever the stream ends or fails. **The server replays nothing and the library sends no
+`Last-Event-ID`:** after `onOpen(true)` you read the home timeline and the notifications again yourself. The events are
+`update`, `notification`, `announcement`, `announcement_removed`, and `unknown` (an event of a newer server; ignore it).
+Abort the signal to stop. See [`examples/stream.ts`](examples/stream.ts) and the
+[mykit README](../README.md#streaming) for what makes it stop.
+
+## Retries, idempotency keys, uploads, admin operations, stability
+
+These work as in the [mykit README](../README.md): 429 and 503 are retried after `Retry-After` for `GET`, `HEAD`, and
+requests with an `Idempotency-Key` (`retry: { disabled, maxRetries, maxWait }`; `maxWait` is in milliseconds); the key
+of a new status is added for you and kept across retries; `uploadMedia(api, { file: blob, description })` uploads a
+`Blob`; the `admin` operations answer 403 to a token of a third-party app; and `/api/v1` follows the
+[stability policy](../README.md#versions-and-api-stability) (a `@deprecated` tag marks what will go).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,36 @@
+import { type Client } from "openapi-fetch";
+import type { paths } from "./schema.gen.js";
+import type { TokenSource } from "./token.js";
+import { type RetryPolicy, type Sleep } from "./transport.js";
+/** The path of the client API under the server's origin (`servers[0].url` of api/openapi.yaml). */
+export declare const apiBasePath = "/api/v1";
+/** The openapi-fetch client of the client API, with the cross-cutting behaviour of the library. */
+export type Api = Client<paths>;
+/** Configures a client of one server. */
+export type ClientOptions = {
+    /** The origin of the server, such as "https://example.com". The client API is under apiBasePath. */
+    server: string;
+    /** Gives the access token of the requests. Absent sends them without one (anonymous). */
+    tokenSource?: TokenSource;
+    /**
+     * Sent as Accept-Language, so that the server localizes the title and detail of its problems. A function is read
+     * for every request, for an app whose locale changes while it runs. Absent leaves it to the server (or the browser).
+     */
+    acceptLanguage?: string | (() => string | null | undefined);
+    /** The policy for 429 and 503 answers; it retries with the defaults when absent. */
+    retry?: RetryPolicy;
+    /** Sends the requests; the global `fetch` by default. */
+    fetch?: (input: Request) => Promise<Response>;
+    /** Waits between retries; for tests. */
+    sleep?: Sleep;
+};
+/**
+ * The client of one server's client API: openapi-fetch typed by the spec, every operation as `GET`, `POST`, ... of
+ * its path. An answer with a status of 400 or more rejects with a ProblemError, and a request that got no answer
+ * with a NetworkError, so `data` is set whenever the call resolves. Middleware added with `use` sees the answer
+ * after the token refresh and the retries, and before the ProblemError. A request given its own `fetch` bypasses
+ * the token, refresh, and retries.
+ */
+export declare function createClient(options: ClientOptions): Api;
+/** Reads the server's origin: an absolute http or https URL without a path, query, or fragment. */
+export declare function parseOrigin(server: string): string;

package/dist/client.js

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: MIT
+import createFetchClient, {} from "openapi-fetch";
+import { acceptsIdempotencyKey, idempotencyKeyHeader } from "./idempotency.js";
+import { problemFromResponse } from "./problem.js";
+import { createTransport } from "./transport.js";
+/** The path of the client API under the server's origin (`servers[0].url` of api/openapi.yaml). */
+export const apiBasePath = "/api/v1";
+/**
+ * The client of one server's client API: openapi-fetch typed by the spec, every operation as `GET`, `POST`, ... of
+ * its path. An answer with a status of 400 or more rejects with a ProblemError, and a request that got no answer
+ * with a NetworkError, so `data` is set whenever the call resolves. Middleware added with `use` sees the answer
+ * after the token refresh and the retries, and before the ProblemError. A request given its own `fetch` bypasses
+ * the token, refresh, and retries.
+ */
+export function createClient(options) {
+    const origin = parseOrigin(options.server);
+    const client = createFetchClient({
+        baseUrl: origin + apiBasePath,
+        fetch: createTransport({
+            fetch: options.fetch ?? ((request) => globalThis.fetch(request)),
+            tokenSource: options.tokenSource,
+            retry: options.retry,
+            ...(options.sleep === undefined ? {} : { sleep: options.sleep }),
+        }),
+    });
+    client.use(middleware(options.acceptLanguage));
+    return client;
+}
+/**
+ * Adds Accept-Language and the Idempotency-Key, and turns an error answer into a ProblemError. It is the first
+ * middleware, so its onResponse runs last.
+ */
+function middleware(acceptLanguage) {
+    return {
+        onRequest({ request, schemaPath }) {
+            const language = typeof acceptLanguage === "function" ? acceptLanguage() : acceptLanguage;
+            if (!request.headers.has("Accept-Language") && language !== undefined && language !== null && language !== "") {
+                request.headers.set("Accept-Language", language);
+            }
+            if (!request.headers.has(idempotencyKeyHeader) && acceptsIdempotencyKey(request.method, schemaPath)) {
+                // One key for every attempt, so that the server applies the request once.
+                request.headers.set(idempotencyKeyHeader, crypto.randomUUID());
+            }
+            return request;
+        },
+        async onResponse({ response }) {
+            if (response.status >= 400)
+                throw await problemFromResponse(response);
+            return undefined;
+        },
+    };
+}
+/** Reads the server's origin: an absolute http or https URL without a path, query, or fragment. */
+export function parseOrigin(server) {
+    if (server === "")
+        throw new Error("mykit: server is empty");
+    let u;
+    try {
+        u = new URL(server);
+    }
+    catch {
+        throw new Error(`mykit: server ${JSON.stringify(server)} is not a URL`);
+    }
+    if ((u.protocol !== "http:" && u.protocol !== "https:") || (u.pathname !== "/" && u.pathname !== "") || u.search !== "" || u.hash !== "") {
+        throw new Error(`mykit: server ${JSON.stringify(server)} is not an origin such as https://example.com`);
+    }
+    return u.origin;
+}

package/dist/idempotency.d.ts

@@ -0,0 +1,13 @@
+/** The header that makes a request safe to send again (draft-ietf-httpapi-idempotency-key-header). */
+export declare const idempotencyKeyHeader = "Idempotency-Key";
+/**
+ * The operations whose spec takes an Idempotency-Key, as the method and the path of the spec (with its `{param}`s).
+ * When the caller sends none, the client adds a new one, so that the request can be retried. A test keeps the list
+ * equal to the operations of schema.gen.ts that take the header.
+ */
+export declare const idempotencyKeyOperations: readonly {
+    readonly method: string;
+    readonly path: string;
+}[];
+/** Whether the request to the spec path `schemaPath` is one of idempotencyKeyOperations. */
+export declare function acceptsIdempotencyKey(method: string, schemaPath: string): boolean;

package/dist/idempotency.js

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+/** The header that makes a request safe to send again (draft-ietf-httpapi-idempotency-key-header). */
+export const idempotencyKeyHeader = "Idempotency-Key";
+/**
+ * The operations whose spec takes an Idempotency-Key, as the method and the path of the spec (with its `{param}`s).
+ * When the caller sends none, the client adds a new one, so that the request can be retried. A test keeps the list
+ * equal to the operations of schema.gen.ts that take the header.
+ */
+export const idempotencyKeyOperations = [{ method: "POST", path: "/statuses" }];
+/** Whether the request to the spec path `schemaPath` is one of idempotencyKeyOperations. */
+export function acceptsIdempotencyKey(method, schemaPath) {
+    const m = method.toUpperCase();
+    return idempotencyKeyOperations.some((op) => op.method === m && op.path === schemaPath);
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { apiBasePath, createClient, type Api, type ClientOptions } from "./client.js";
+export { idempotencyKeyOperations } from "./idempotency.js";
+export { codeChallenge, exchange, newCodeVerifier, OAuthError, tokenPath, type OAuthConfig } from "./oauth.js";
+export { all, type Page, type PageFetcher } from "./paging.js";
+export { NetworkError, ProblemError, problemFromResponse, problemTypeAboutBlank, type Problem } from "./problem.js";
+export type { components, operations, paths } from "./schema.gen.js";
+export { defaultHeartbeatTimeout, HeartbeatTimeoutError, NotEventStreamError, runStream, type StreamEvent, type StreamOptions, } from "./stream.js";
+export { RefreshingTokenSource, staticToken, type OnTokens, type Token, type TokenSource } from "./token.js";
+export type { RetryPolicy, Sleep } from "./transport.js";
+export { uploadMedia, type MediaAttachment, type MediaUploadInput, type MediaUploadPurpose } from "./upload.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+// @mycroblog/mykit: the client of the mycroblog/my client API (ADR-0093). The types are generated from the spec
+// (schema.gen.ts); the hand-written layer adds the cross-cutting behaviour only: the access token and its refresh,
+// Accept-Language, RFC 9457 errors, cursor pagination, retries after 429 and 503, the Idempotency-Key, media upload,
+// PKCE, and the client of the event stream.
+export { apiBasePath, createClient } from "./client.js";
+export { idempotencyKeyOperations } from "./idempotency.js";
+export { codeChallenge, exchange, newCodeVerifier, OAuthError, tokenPath } from "./oauth.js";
+export { all } from "./paging.js";
+export { NetworkError, ProblemError, problemFromResponse, problemTypeAboutBlank } from "./problem.js";
+export { defaultHeartbeatTimeout, HeartbeatTimeoutError, NotEventStreamError, runStream, } from "./stream.js";
+export { RefreshingTokenSource, staticToken } from "./token.js";
+export { uploadMedia } from "./upload.js";

package/dist/oauth.d.ts

@@ -0,0 +1,39 @@
+import type { Token } from "./token.js";
+/** The path of the server's token endpoint under its origin. */
+export declare const tokenPath = "/oauth/token";
+/** The client's registration on a server's authorization server (ADR-0090). */
+export type OAuthConfig = {
+    /** The origin of the server, such as "https://example.com". */
+    server: string;
+    /** The client_id of the registration, or the URL of the client's metadata document. */
+    clientId: string;
+    /** The secret of a confidential client; absent for a public client. */
+    clientSecret?: string;
+    /** The redirect_uri that the authorization request sent. */
+    redirectUri?: string;
+    /** Sends the requests to the token endpoint; the global `fetch` by default. */
+    fetch?: (input: Request) => Promise<Response>;
+};
+/** A new PKCE code_verifier (RFC 7636 §4.1): 32 random bytes, base64url-encoded. */
+export declare function newCodeVerifier(): string;
+/** The S256 code_challenge of a code_verifier (RFC 7636 §4.2), the only method the server accepts. */
+export declare function codeChallenge(verifier: string): Promise<string>;
+/**
+ * Exchanges the authorization code that the redirect brought for the tokens, with the code_verifier whose challenge
+ * the authorization request sent.
+ */
+export declare function exchange(oauth: OAuthConfig, code: string, verifier: string): Promise<Token>;
+/** An error answer of the token endpoint (RFC 6749 §5.2). */
+export declare class OAuthError extends Error {
+    readonly name = "OAuthError";
+    /** The HTTP status of the answer. */
+    readonly status: number;
+    /** The error code, such as "invalid_grant". */
+    readonly code: string;
+    readonly description: string;
+    constructor(status: number, code: string, description?: string);
+}
+/** Posts a grant to the token endpoint, with the client's credentials, and reads the tokens. */
+export declare function tokenRequest(oauth: OAuthConfig, params: Record<string, string>): Promise<Token>;
+/** Whether error is the rejection of an aborted request. */
+export declare function isAbort(error: unknown): boolean;

package/dist/oauth.js

@@ -0,0 +1,119 @@
+import { NetworkError } from "./problem.js";
+/** The path of the server's token endpoint under its origin. */
+export const tokenPath = "/oauth/token";
+/** Encodes bytes as base64url without padding. */
+function base64url(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+/** A new PKCE code_verifier (RFC 7636 §4.1): 32 random bytes, base64url-encoded. */
+export function newCodeVerifier() {
+    return base64url(crypto.getRandomValues(new Uint8Array(32)));
+}
+/** The S256 code_challenge of a code_verifier (RFC 7636 §4.2), the only method the server accepts. */
+export async function codeChallenge(verifier) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+    return base64url(new Uint8Array(digest));
+}
+/**
+ * Exchanges the authorization code that the redirect brought for the tokens, with the code_verifier whose challenge
+ * the authorization request sent.
+ */
+export function exchange(oauth, code, verifier) {
+    return tokenRequest(oauth, {
+        grant_type: "authorization_code",
+        code,
+        code_verifier: verifier,
+        redirect_uri: oauth.redirectUri ?? "",
+    });
+}
+/** An error answer of the token endpoint (RFC 6749 §5.2). */
+export class OAuthError extends Error {
+    name = "OAuthError";
+    /** The HTTP status of the answer. */
+    status;
+    /** The error code, such as "invalid_grant". */
+    code;
+    description;
+    constructor(status, code, description = "") {
+        super(`mykit: oauth: ${code}${description === "" ? "" : `: ${description}`}`);
+        this.status = status;
+        this.code = code;
+        this.description = description;
+    }
+}
+/** The form encoding of RFC 6749 Appendix B, which the client credentials get before they go into Basic. */
+function formEncode(s) {
+    return new URLSearchParams({ s }).toString().slice("s=".length);
+}
+/** Posts a grant to the token endpoint, with the client's credentials, and reads the tokens. */
+export async function tokenRequest(oauth, params) {
+    const endpoint = new URL(tokenPath, oauth.server).href;
+    const form = new URLSearchParams();
+    for (const [k, v] of Object.entries(params))
+        if (v !== "")
+            form.set(k, v);
+    const headers = new Headers({ "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" });
+    if (oauth.clientSecret === undefined || oauth.clientSecret === "") {
+        form.set("client_id", oauth.clientId);
+    }
+    else {
+        // RFC 6749 §2.3.1: the credentials are form-encoded before they go into Basic.
+        const credentials = `${formEncode(oauth.clientId)}:${formEncode(oauth.clientSecret)}`;
+        headers.set("Authorization", `Basic ${btoa(String.fromCharCode(...new TextEncoder().encode(credentials)))}`);
+    }
+    const fetch = oauth.fetch ?? ((request) => globalThis.fetch(request));
+    const now = Date.now();
+    let response;
+    let body;
+    try {
+        response = await fetch(new Request(endpoint, { method: "POST", headers, body: form }));
+        body = await response.text();
+    }
+    catch (error) {
+        if (isAbort(error))
+            throw error;
+        throw new NetworkError("POST", endpoint, error);
+    }
+    if (response.status !== 200) {
+        let code = "";
+        let description = "";
+        if (response.headers.get("Content-Type")?.split(";")[0]?.trim() === "application/json") {
+            try {
+                const v = JSON.parse(body);
+                if (typeof v.error === "string")
+                    code = v.error;
+                if (typeof v.error_description === "string")
+                    description = v.error_description;
+            }
+            catch {
+                // No error document: the status below.
+            }
+        }
+        throw new OAuthError(response.status, code === "" ? response.statusText || String(response.status) : code, description);
+    }
+    let tr;
+    try {
+        tr = JSON.parse(body);
+    }
+    catch (error) {
+        throw new OAuthError(response.status, "invalid_response", error instanceof Error ? error.message : String(error));
+    }
+    if (typeof tr.access_token !== "string" || tr.access_token === "" || typeof tr.token_type !== "string" || tr.token_type.toLowerCase() !== "bearer") {
+        throw new OAuthError(response.status, "invalid_response", "no bearer access token");
+    }
+    const token = { accessToken: tr.access_token };
+    if (typeof tr.refresh_token === "string" && tr.refresh_token !== "")
+        token.refreshToken = tr.refresh_token;
+    if (typeof tr.scope === "string")
+        token.scope = tr.scope;
+    if (typeof tr.expires_in === "number" && tr.expires_in > 0)
+        token.expiresAt = now + tr.expires_in * 1000;
+    return token;
+}
+/** Whether error is the rejection of an aborted request. */
+export function isAbort(error) {
+    return error instanceof DOMException && (error.name === "AbortError" || error.name === "TimeoutError");
+}

package/dist/paging.d.ts

@@ -0,0 +1,25 @@
+/** A page of a collection with keyset pagination: its items and the cursor of the next page. */
+export type Page<T> = {
+    readonly items: readonly T[];
+    /** The cursor of the next page; absent, null, or empty on the last page. */
+    readonly next_cursor?: string | null;
+};
+/** Fetches the page of a collection that cursor names (undefined for the first page). */
+export type PageFetcher<T> = (cursor: string | undefined) => Promise<Page<T>>;
+/**
+ * Iterates the items of a collection with keyset pagination, fetching the pages one by one as the loop needs them by
+ * following next_cursor. It stops after the last page, rejects at the first error, and fetches no more when the loop
+ * breaks:
+ *
+ * ```ts
+ * for await (const status of all(async (cursor) => {
+ *   const { data } = await api.GET("/timelines/home", { params: { query: { cursor } } });
+ *   return data!;
+ * })) {
+ *   console.log(status.id);
+ * }
+ * ```
+ *
+ * A timeline has no end: break out of the loop when you have seen enough.
+ */
+export declare function all<T>(fetch: PageFetcher<T>): AsyncGenerator<T, void, undefined>;

package/dist/paging.js

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Iterates the items of a collection with keyset pagination, fetching the pages one by one as the loop needs them by
+ * following next_cursor. It stops after the last page, rejects at the first error, and fetches no more when the loop
+ * breaks:
+ *
+ * ```ts
+ * for await (const status of all(async (cursor) => {
+ *   const { data } = await api.GET("/timelines/home", { params: { query: { cursor } } });
+ *   return data!;
+ * })) {
+ *   console.log(status.id);
+ * }
+ * ```
+ *
+ * A timeline has no end: break out of the loop when you have seen enough.
+ */
+export async function* all(fetch) {
+    let cursor;
+    for (;;) {
+        const page = await fetch(cursor);
+        yield* page.items;
+        if (page.next_cursor === undefined || page.next_cursor === null || page.next_cursor === "")
+            return;
+        cursor = page.next_cursor;
+    }
+}

package/dist/problem.d.ts

@@ -0,0 +1,47 @@
+import type { components } from "./schema.gen.js";
+/** The RFC 9457 problem document of an answer with a status of 400 or more, with its extension members. */
+export type Problem = components["schemas"]["Problem"] & Record<string, unknown>;
+/** The type of a problem that means no more than its HTTP status (RFC 9457 §4.2.1). */
+export declare const problemTypeAboutBlank = "about:blank";
+/**
+ * The error of an answer with a status of 400 or more: its RFC 9457 problem document.
+ *
+ * ```ts
+ * try { await api.POST("/statuses", { body }); }
+ * catch (e) { if (e instanceof ProblemError && e.type === "/api/v1/problems/blocking") { ... } }
+ * ```
+ *
+ * Branch on `type` and `status`, never on `title` or `detail`, which the server localizes from Accept-Language. The
+ * members beyond the standard ones (such as `reason`) are in `problem`.
+ */
+export declare class ProblemError extends Error {
+    readonly name = "ProblemError";
+    /** The whole problem document, extension members included. */
+    readonly problem: Problem;
+    /** The headers of the answer, such as Retry-After and WWW-Authenticate. */
+    readonly headers: Headers;
+    constructor(problem: Problem, headers: Headers);
+    /** The URI that identifies the problem type, `about:blank` when the problem means no more than its status. */
+    get type(): string;
+    /** The HTTP status of the answer. */
+    get status(): number;
+    /** The localized summary of the problem type. */
+    get title(): string;
+    /** The localized explanation of this occurrence. */
+    get detail(): string | undefined;
+}
+/**
+ * Reads the problem of an error answer. An answer that is no problem document (from a proxy, say) becomes a problem
+ * of type about:blank with the answer's status.
+ */
+export declare function problemFromResponse(response: Response): Promise<ProblemError>;
+/**
+ * The failure to get an answer from the server: the connection, TLS, or the fetch implementation. Its `cause` is the
+ * error of `fetch`. An aborted request is not one: it rejects with the reason of its signal (an AbortError).
+ */
+export declare class NetworkError extends Error {
+    readonly name = "NetworkError";
+    readonly method: string;
+    readonly url: string;
+    constructor(method: string, url: string, cause: unknown);
+}