@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/api-key.d.ts

@@ -0,0 +1,79 @@
+/** The fixed, greppable prefix. `ak1` is the format version. ⚠ Must match what the server issues. */
+export declare const KEY_PREFIX = "nmts_ak1_";
+/** base64url over 9 random bytes. PUBLIC — this is the handle the account screen lists. */
+export declare const KEY_HANDLE_LEN = 12;
+/** One line, exactly this long: 9 + 12 + 1 + 43. */
+export declare const KEY_LEN: number;
+/**
+ * What a string turns out to be.
+ *
+ * ⛔ NO VARIANT CARRIES THE VALUE. A shape that held the offending string would be a credential in
+ *    every error message built from it, which is the hole `errors.ts` spends a paragraph on.
+ */
+export type KeyShape = {
+    readonly kind: "key";
+    readonly handle: string;
+} | {
+    readonly kind: "malformed";
+} | {
+    readonly kind: "not-a-key";
+};
+/**
+ * Decide what a string is, without touching the network.
+ *
+ * ⛔ PARSED BY FIXED OFFSETS, NEVER BY SPLITTING ON `_`. The base64url alphabet contains `_`, so
+ *    splitting cuts the string in a place that depends on its random bytes: the same code would
+ *    accept one key and mangle the next. The Rust side says the same thing in the same words.
+ */
+export declare function wellFormed(value: string): KeyShape;
+/** Where an offered key came from. Reported, never guessed. */
+export type KeyOffer = "secret-file" | "env" | "terminal";
+/**
+ * What `login` decided about the API key.
+ *
+ * ⛔ FOUR CASES AND NOT A NULLABLE STRING. "No key at all" and "the key that was already here" are
+ *    different things to a person setting this tool up for the first time: one of them means every
+ *    command that talks to the server is about to refuse, and that is the sentence they need. A
+ *    single `string | undefined` would compile everywhere and say nothing.
+ */
+export type KeyOutcome = {
+    readonly kind: "none";
+} | {
+    readonly kind: "unchanged";
+    readonly apiKey: string;
+} | {
+    readonly kind: "stored";
+    readonly apiKey: string;
+    readonly handle: string;
+    /** Whether a person's periodic check is live for this account right now. */
+    readonly verified: boolean;
+    readonly from: KeyOffer;
+} | {
+    readonly kind: "kept";
+    readonly apiKey: string;
+    readonly from: KeyOffer;
+};
+export interface KeyIntake {
+    /** The server the key will be checked against, and the one it belongs to. */
+    server: string;
+    /** What is already stored on this machine, if anything. */
+    stored: string | undefined;
+    /** Injected in tests so the terminal is not involved. An empty answer means "not now". */
+    readKey?: (() => Promise<string>) | undefined;
+    /** Injected in tests. Answers the question that replaces a stored key. */
+    confirmReplace?: (() => Promise<string>) | undefined;
+}
+/** The key to write down, or nothing. */
+export declare function keyToStore(outcome: KeyOutcome): string | undefined;
+/** The name of the place a key was offered from, for a message that has to say which one. */
+export declare function keySourceName(from: KeyOffer): string;
+/**
+ * Work out which key this machine should end up with, checking any new one before it is written.
+ *
+ * ⛔ A KEY ALREADY HERE IS NEVER REPLACED BY A RUN THAT DID NOT SAY SO. `login` is a command about
+ *    the NMTS key; a person re-sealing their code with a new passphrase, on a machine where an
+ *    old variable is still set in some shell profile, has not asked for their working key to be
+ *    swapped for whatever that variable holds. Silently overwriting it would break every agent on
+ *    the machine at a moment nobody would connect to the command they ran.
+ */
+export declare function settleApiKey(intake: KeyIntake): Promise<KeyOutcome>;

package/dist/api-key.js

@@ -10,11 +10,11 @@
 // ⛔ NEVER FROM THE COMMAND LINE, for the reason written at the top of `credentials.ts`: on Linux
 //    any process can read another's /proc/<pid>/cmdline for as long as it lives, and the shell
 //    writes it to a history file. So there is no --api-key flag here and there never should be.
-//    The ways in are the three the account code already has — a file an environment variable
+//    The ways in are the three the NMTS key already has — a file an environment variable
 //    NAMES, the variable itself, and a prompt that echoes nothing.
 //
 // ⛔ THE SHAPE IS JUDGED HERE, BEFORE ANYTHING LEAVES THIS MACHINE, and that is not tidiness. The
-//    likeliest wrong thing to paste where a key is asked for is the ACCOUNT CODE, and sending it
+//    likeliest wrong thing to paste where a key is asked for is the NMTS KEY, and sending it
 //    as a bearer token would put the one secret this product promises never travels onto the wire,
 //    into whatever sits in front of the server, and into its logs. The server does classify it and
 //    refuse (`ACCOUNT_CODE_NOT_A_CREDENTIAL`) rather than store it — but that answer arrives after
@@ -28,7 +28,7 @@
 //   half-accepting.
 //
 // ⛔ AND NO FIFTH CONSENT KEY. `consent.ts` allows four and says why: the bar is that the thing
-//    cannot be undone, costs money, or puts the ACCOUNT CODE somewhere that is not this tool's
+//    cannot be undone, costs money, or puts the NMTS KEY somewhere that is not this tool's
 //    sealed file. A key is none of the three — it opens no ciphertext, the account screen revokes
 //    it, it expires by itself, and every command in this tool already reads it out of the
 //    environment without asking. A fifth question here is a fifth chance to teach somebody to
@@ -94,7 +94,7 @@ export function keySourceName(from) {
  * Work out which key this machine should end up with, checking any new one before it is written.
  *
  * ⛔ A KEY ALREADY HERE IS NEVER REPLACED BY A RUN THAT DID NOT SAY SO. `login` is a command about
- *    the account code; a person re-sealing their code with a new passphrase, on a machine where an
+ *    the NMTS key; a person re-sealing their code with a new passphrase, on a machine where an
  *    old variable is still set in some shell profile, has not asked for their working key to be
  *    swapped for whatever that variable holds. Silently overwriting it would break every agent on
  *    the machine at a moment nobody would connect to the command they ran.
@@ -270,9 +270,9 @@ async function refuse(shape, value) {
         });
     }
     if (await looksLikeAnAccountCode(value)) {
-        return new NmtsError(`That is an account code, not an API key.`, {
+        return new NmtsError(`That is an NMTS key, not an API key.`, {
             exitCode: 2,
-            nextStep: `It was NOT sent anywhere: the account code stays on this machine, and it is what opens ` +
+            nextStep: `It was NOT sent anywhere: the NMTS key stays on this machine, and it is what opens ` +
                 `your files. An API key is a different thing — it makes the server answer a program, and ` +
                 `it opens nothing. Make one on the account screen at ${HOME_URL}; it begins ` +
                 `\`${KEY_PREFIX}\`. ${NOTHING_WAS_WRITTEN}`,
@@ -285,7 +285,7 @@ async function refuse(shape, value) {
     });
 }
 /**
- * Is this the account code, pasted where the key goes?
+ * Is this the NMTS key, pasted where the key goes?
  *
  * ⛔ ASKED OF THE ENGINE'S OWN PARSER, which verifies the code's trailing check symbol. Copying the
  *    alphabet here would be a second implementation of a format this repo keeps in exactly one

package/dist/api-refusal.d.ts

@@ -0,0 +1,14 @@
+export interface ServerRefusal {
+    code: string;
+    message: string;
+    /**
+     * Whatever the refusal carries beside its words — a limit that was hit, an address to go to.
+     *
+     * ⚠ Values are not all numbers: `AGENT_VERIFY_REQUIRED` names the page a person opens. Nothing
+     *   here validates the shape, so a narrower type than the wire's would be a claim, not a check.
+     */
+    details?: Record<string, string | number>;
+}
+export declare function isRefusal(value: unknown): value is {
+    error: ServerRefusal;
+};

package/dist/api-refusal.js

@@ -0,0 +1,8 @@
+export function isRefusal(value) {
+    if (typeof value !== "object" || value === null || !("error" in value))
+        return false;
+    const error = Reflect.get(value, "error");
+    if (typeof error !== "object" || error === null)
+        return false;
+    return typeof Reflect.get(error, "code") === "string" && typeof Reflect.get(error, "message") === "string";
+}

package/dist/api.d.ts

@@ -0,0 +1,114 @@
+import { NmtsError } from "./errors.ts";
+import { type WaitReporter } from "./net-retry.ts";
+/** Default deadline for a request that is not moving file bytes. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export type { ServerRefusal } from "./api-refusal.ts";
+import type { ServerRefusal } from "./api-refusal.ts";
+/** A refusal the server explained. Carries its code so a caller can branch without string matching. */
+export declare class ServerError extends NmtsError {
+    readonly status: number;
+    readonly code: string;
+    /** Seconds to wait. ⛔ `Retry-After` is the only place the server sends it — never the body. */
+    readonly retryAfter: number | null;
+    /**
+     * Whatever the refusal carried beside its words — the two credit amounts a doubled release fee
+     * is refused with, a limit that was hit, an address to go to.
+     *
+     * ⚠ NOT VALIDATED HERE. It arrives from the network and every reader checks the one field it
+     *   wants before printing it; a narrower type would be a claim rather than a check.
+     */
+    readonly details: Readonly<Record<string, string | number>>;
+    constructor(status: number, refusal: ServerRefusal, nextStep: string | null, retryAfter?: number | null);
+}
+/**
+ * A failure the server did NOT explain: a status with no refusal body behind it.
+ *
+ * ⛔ IT CARRIES THE STATUS SO A CALLER NEED NOT MATCH ON THE MESSAGE. The routes that serve
+ *    documents answer 404 with an empty body for an id nothing has — there is no code to branch
+ *    on, and "read the message and look for 404 in it" is how a refusal ends up being decided by
+ *    a sentence somebody later rewrote. It extends `NmtsError` and changes nothing about how this
+ *    failure is retried, reported or exited: only that a caller can now ask what the status was.
+ */
+export declare class HttpError extends NmtsError {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * A body the server sent as text, and the name its `Content-Disposition` gives that text.
+ *
+ * ⛔ THE NAME IS THE SERVER'S, NOT THIS TOOL'S. A notice kept from a terminal and the same notice
+ *    kept from the browser's download button should be the same bytes under the same name, and
+ *    the only way to be sure of that is to take the name from the one place both clients read it.
+ *    ⚠ It is still a name that arrived over the network: whatever writes a file with it puts it
+ *      through `safe-path.ts` first.
+ */
+export interface TextAnswer {
+    readonly text: string;
+    /** Null when the answer named no file. */
+    readonly filename: string | null;
+}
+export interface RequestOptions {
+    method?: "GET" | "POST" | "PUT" | "DELETE";
+    body?: unknown;
+    /** Session bearer token. Sent in the Authorization header and nowhere else. */
+    token?: string | undefined;
+    timeoutMs?: number;
+    signal?: AbortSignal | undefined;
+    /**
+     * Told before each wait between attempts, so a terminal can say the tool is waiting.
+     *
+     * ⛔ NOTHING IS RETRIED SILENTLY. A person watching and an agent reading the output both need to
+     *    know the difference between a tool that is waiting and one that is stuck.
+     */
+    onWait?: WaitReporter;
+    /**
+     * How long to keep trying a request that is safe to repeat. Omit for the default.
+     *
+     * ⛔ 0 MEANS ONE ATTEMPT. That is what a caller measuring the shape of a single failure wants,
+     *    and it is the only way to ask for it — there is no separate "no retry" flag to fall out of
+     *    step with this one.
+     */
+    retryBudgetMs?: number;
+    /**
+     * Make this request safe to repeat.
+     *
+     * ⛔ A NARROW OPTION RATHER THAN ARBITRARY HEADERS. The two calls that need it are the two that
+     *    SPEND -- committing a file and reserving storage -- and a general header bag on a client
+     *    that carries a bearer token is a way to send that token somewhere it was not meant to go.
+     */
+    idempotencyKey?: string;
+    /**
+     * Proof that this run holds the NMTS key, for the three routes that ask for one.
+     *
+     * ⛔ A NAMED OPTION, FOR THE SAME REASON `idempotencyKey` IS ONE. A general header bag on a
+     *    client that carries a bearer token is a way to send that token somewhere it was not meant
+     *    to go; this is one field, filled by one module, and it reaches exactly one header.
+     *
+     * ⛔ ITS VALUE IS NEVER IN A MESSAGE, A URL OR A LOG. `account-proof.ts` says what it is and
+     *    what it can still do if it leaks. The server refuses to log it either — see
+     *    `ACCOUNT_PROOF_HEADER` in `api/src/auth/api_key_auth.rs`.
+     */
+    accountProof?: string;
+    /**
+     * What the answer is. Absent means JSON, which is what every `/v1` route sends.
+     *
+     * ⛔ ONE OPTION RATHER THAN A SECOND CLIENT. The site serves three documents as text — the
+     *    notice board's rows, one notice, one legal document — and a separate fetch for them would
+     *    be a second place holding the deadline, the retry rule, the run log and the refusal
+     *    reading. Two of those going out of step is not hypothetical here: `check:cli-routes` exists
+     *    because a command once called an address the server did not have, and it can only see
+     *    calls that come through this function.
+     */
+    as?: "text";
+}
+/**
+ * One request to the NMTS server, returning parsed JSON or throwing a named refusal.
+ *
+ * `path` starts with `/v1/` for the API, or `/api/` for the three documents the site itself
+ * serves. It is joined to the base without any normalising, so a caller cannot accidentally send
+ * a request to a different host by passing an absolute URL.
+ */
+export declare function request(base: string, path: string, options: RequestOptions & {
+    as: "text";
+}): Promise<TextAnswer>;
+export declare function request(base: string, path: string, options?: RequestOptions): Promise<unknown>;

package/dist/api.js

@@ -10,181 +10,53 @@
 //    that hangs forever is worse than one that fails, because nothing ever reports it.
 //
 // ⛔ THE TOKEN IS NEVER IN A MESSAGE, A URL OR A LOG. It goes in one header and nowhere else.
+import { adviseFor } from "./api-advice.js";
 import { NmtsError } from "./errors.js";
 import { isTransient, keepTrying } from "./net-retry.js";
+import { noteRequest } from "./run-log.js";
 /** Default deadline for a request that is not moving file bytes. */
 export const DEFAULT_TIMEOUT_MS = 30_000;
+import { isRefusal } from "./api-refusal.js";
 /** A refusal the server explained. Carries its code so a caller can branch without string matching. */
 export class ServerError extends NmtsError {
     status;
     code;
-    constructor(status, refusal, nextStep) {
+    /** Seconds to wait. ⛔ `Retry-After` is the only place the server sends it — never the body. */
+    retryAfter;
+    /**
+     * Whatever the refusal carried beside its words — the two credit amounts a doubled release fee
+     * is refused with, a limit that was hit, an address to go to.
+     *
+     * ⚠ NOT VALIDATED HERE. It arrives from the network and every reader checks the one field it
+     *   wants before printing it; a narrower type would be a claim rather than a check.
+     */
+    details;
+    constructor(status, refusal, nextStep, retryAfter = null) {
         super(refusal.message, { exitCode: 1, nextStep });
         this.name = "ServerError";
         this.status = status;
         this.code = refusal.code;
+        this.retryAfter = retryAfter;
+        this.details = refusal.details ?? {};
     }
 }
-/** What a caller does next about a refusal, when the tool knows something the message does not. */
-function adviseFor(code) {
-    switch (code) {
-        case "CLEARANCE_REQUIRED":
-        case "TURNSTILE_FAILED":
-            return ("This account needs a human check, which a command-line tool cannot pass. An API key " +
-                "made on the account screen is what waives it — put it in NMTS_API_KEY. If that screen " +
-                "has no place to make one, this server does not have API keys switched on.");
-        case "UNAUTHORIZED":
-            return "The credential is missing or expired. Check NMTS_API_KEY, or make a new key.";
-        // ⛔ Each of these says something different on purpose, because the remedies are different
-        //    and a program that cannot tell them apart will retry the one thing that cannot work.
-        case "SESSION_REVOKED":
-            return "That is a browser session somebody ended from another device, not an API key. A key is what a program should carry; NMTS_API_KEY is where it goes.";
-        case "API_KEY_REVOKED":
-            return "Somebody revoked this key. It will not start working again — make a new one.";
-        case "API_KEY_EXPIRED":
-            return "This key reached the end of the lifetime it was given. Make a new one.";
-        case "API_KEY_SCOPE":
-            return ("The key is valid and was not given permission for this. Nothing here will succeed with " +
-                "it — a key with the right permissions has to be made on the account screen.");
-        case "API_KEY_MALFORMED":
-            return ("What was sent is not a well-formed key. Check that the whole string was copied, with " +
-                "no quotes or line break — it is one line of exactly 65 characters.");
-        case "ACCOUNT_CODE_NOT_A_CREDENTIAL":
-            return ("That was an account code, not an API key. The code never goes to the server; it stays " +
-                "on this machine and opens the files. Put the code in NMTS_ACCOUNT_CODE and the key in " +
-                "NMTS_API_KEY.");
-        case "AGENT_VERIFY_REQUIRED":
-            return ("This was refused because nothing has checked lately that a person is behind this " +
-                "account's key. Ask the person to run `nmts verify` and to follow what it prints — it " +
-                "gives them a code to type at a browser, and nothing here can pass that check for them.");
-        // ⛔ THE REFUSAL IS CORRECT AND THERE IS NOTHING HERE TO WORK AROUND. Accepting terms is a
-        //    person reading a document and agreeing to it; a program doing it for them would be
-        //    signing on somebody else's behalf, and this tool holds an API key, not a person. So the
-        //    only thing missing was the advice — without it an agent gets a bare 403 and starts
-        //    trying credentials, which is the one thing that cannot be the cause.
-        //
-        // ⚠ It does not say WHICH requests are refused. The server gates some and not others (reading
-        //   and deleting are not gated today), that line has moved twice, and a sentence here naming
-        //   the list would be a copy of it that nothing keeps true.
-        case "TERMS_ACCEPTANCE_REQUIRED":
-            return ("This account has not accepted the terms now in force, and the server refuses this " +
-                "request until it does. Nothing on this machine can accept them. Ask the person to open " +
-                "the account screen at nmts.me and accept there. Other requests may still work in the " +
-                "meantime.");
-        // ⛔ A KEY IS NOT ENOUGH HERE AND NEVER WILL BE. These routes rebuild what makes the account
-        //    recoverable without NMTS, and the owner's rule is that the code is re-entered for them.
-        //    An agent that reads this as "my key is wrong" starts making new keys, which is the one
-        //    remedy that cannot work.
-        case "ACCOUNT_PROOF_REQUIRED":
-            return ("This request needs proof of the account code as well as the key, and what was sent was " +
-                "missing or did not match. Check that the code this machine is holding belongs to the " +
-                "same account as the key. Wrong attempts are counted, and three of them lock these " +
-                "routes for a while.");
-        case "ACCOUNT_BANNED":
-            return "This account is suspended. Nothing here will succeed until that is lifted.";
-        // ── Getting to the starting line ──────────────────────────────────────────────────────────
-        case "ACCOUNT_EXISTS":
-            return "An account already exists for that. Use the one you have rather than making another.";
-        case "ALPHA_NOT_OPEN":
-            return ("This build asks the server for a channel it does not open. This is not something to " +
-                "retry or to fix with a different credential — use a release build.");
-        case "API_KEY_CAP":
-            return ("The account holds as many live keys as it is allowed. Nothing here can raise the limit: " +
-                "the person has to revoke a key they no longer use, on the account screen at nmts.me.");
-        case "API_KEY_CHANNEL":
-            return ("This account is enrolled on a preview build, and keys are not issued while it is. Ask " +
-                "the person to leave the preview on the account screen, then make the key.");
-        case "INVALID_CREDENTIALS":
-            return ("The server did not accept what was sent. Check the key rather than the account code — " +
-                "the code never goes to the server and cannot be the cause.");
-        case "LOCKED_OUT":
-            return ("Too many failed attempts, so this is shut for a while. Retrying now makes it longer, " +
-                "not shorter. The refusal carries the moment it lifts; wait for it.");
-        case "RATE_LIMITED":
-            return ("Too many requests too quickly. Wait and send fewer — the refusal carries how long. This " +
-                "is not a credential problem, so changing keys will not help.");
-        case "SURFACE_MISMATCH":
-            return ("This account acts through a different build than the one calling. The refusal names " +
-                "which; nothing on this machine can change it, and the person switches it at nmts.me.");
-        // ── The terms ─────────────────────────────────────────────────────────────────────────────
-        case "TERMS_VERSION_MISMATCH":
-            return ("The versions sent are not the ones in force; the refusal carries the ones that are. " +
-                "This is a stale copy, not a refusal to serve — read the current versions and send those.");
-        case "TERMS_NOT_IN_FORCE":
-            return ("There is nothing to accept, so accepting cannot be what is missing. This is a server " +
-                "condition; report it rather than retrying.");
-        // ── Credits and the free trial ────────────────────────────────────────────────────────────
-        case "CREDIT_FILE_CAP":
-            return ("One file may cost at most the published cap in credits, and this one costs more. The " +
-                "refusal carries both numbers. Splitting the file is the way through; more credits is not.");
-        case "CREDIT_DAILY_CAP":
-            return ("The account has spent its allowance for today. The refusal carries the cap and what is " +
-                "spent. Waiting for the day to turn is the only remedy — buying credits does not lift it.");
-        case "TRIAL_CLOSED":
-            return "The free trial is not open at all right now. Credits have to come from a funded wallet.";
-        case "TRIAL_FULL":
-            return "This week's free-trial places are taken. Applying again this week cannot succeed; next week can.";
-        case "TRIAL_ALREADY":
-            return "This account already took the free trial this week. It comes round weekly, not once.";
-        case "TRIAL_HELD":
-            return "Free-trial applications are paused pending review. Retrying does not move it.";
-        case "TRIAL_LINE_CAPPED":
-            return ("This internet connection has taken its share of this week's places today — the limit is " +
-                "on the connection, not on the account, so another account here hits it too.");
-        // ── Storage, the chain, and what is safe to retry ─────────────────────────────────────────
-        // ⛔ THE THREE OUTCOMES ARE DIFFERENT AND AN AGENT MUST NOT COLLAPSE THEM. Refused means it did
-        //    not happen. Failed means it did not finish. Uncertain means nobody knows — and that is the
-        //    one where retrying blindly can spend money twice.
-        case "CHAIN_REQUEST_REFUSED":
-            return ("The storage service refused the request itself, so nothing was spent and nothing was " +
-                "stored. Retrying the same request will be refused the same way.");
-        case "CHAIN_REGISTER_FAILED":
-            return "Registering the storage did not go through. Nothing is stored; the upload can be tried again.";
-        case "CHAIN_CERTIFY_FAILED":
-            return ("The bytes went out but the storage was never certified, so the file is not safely stored. " +
-                "Try the upload again.");
-        case "CHAIN_UNCERTAIN":
-            return ("⛔ Nobody knows whether the storage was registered. Do NOT simply retry: doing so can pay " +
-                "twice for the same file. Run `nmts ls` first and see whether the file is there.");
-        case "CHAIN_SPEND_CAP":
-            return ("The service has stopped spending on storage for today. This is not about this account " +
-                "and no credential or credit changes it. Try tomorrow.");
-        case "CHAIN_DELETE_FAILED":
-            return ("The storage could not be released. The file's record is gone from this side either way, " +
-                "so nothing here is stuck — the storage runs out on its own when its time is up.");
-        case "RELEASE_NOT_SPONSORED":
-            return ("This file's storage was not paid for with credits, so it is not the server's to release. " +
-                "Storage bought from a wallet is released by that wallet.");
-        case "SPONSORED_STATE":
-            return ("The upload is not at the step that call belongs to — the steps have an order and one was " +
-                "skipped or already done. Start the upload again rather than repeating this call.");
-        // ── Two callers, one drive ────────────────────────────────────────────────────────────────
-        case "VERSION_CONFLICT":
-            return ("Something else changed the drive since this was read. Nothing is lost and nothing is " +
-                "wrong with the credential: read the current state and apply the change to that.");
-        case "ERASE_BLOCKED":
-            return ("The account cannot be erased while retained records still point at it. This will not " +
-                "clear by retrying; the records have their own retention and it has to run out.");
-        case "CREDITS_SHORT":
-            return "The account does not have enough credits for this upload.";
-        default:
-            return null;
-    }
-}
-function isRefusal(value) {
-    if (typeof value !== "object" || value === null || !("error" in value))
-        return false;
-    const error = Reflect.get(value, "error");
-    if (typeof error !== "object" || error === null)
-        return false;
-    return typeof Reflect.get(error, "code") === "string" && typeof Reflect.get(error, "message") === "string";
-}
 /**
- * One request to the NMTS server, returning parsed JSON or throwing a named refusal.
+ * A failure the server did NOT explain: a status with no refusal body behind it.
  *
- * `path` starts with `/v1/`. It is joined to the base without any normalising, so a caller cannot
- * accidentally send a request to a different host by passing an absolute URL.
+ * ⛔ IT CARRIES THE STATUS SO A CALLER NEED NOT MATCH ON THE MESSAGE. The routes that serve
+ *    documents answer 404 with an empty body for an id nothing has — there is no code to branch
+ *    on, and "read the message and look for 404 in it" is how a refusal ends up being decided by
+ *    a sentence somebody later rewrote. It extends `NmtsError` and changes nothing about how this
+ *    failure is retried, reported or exited: only that a caller can now ask what the status was.
  */
+export class HttpError extends NmtsError {
+    status;
+    constructor(status, message) {
+        super(message, { exitCode: 1 });
+        this.name = "HttpError";
+        this.status = status;
+    }
+}
 export async function request(base, path, options = {}) {
     if (!path.startsWith("/"))
         throw new NmtsError(`A request path must start with "/": ${path}`);
@@ -211,7 +83,9 @@ async function once(base, path, options) {
     const deadline = setTimeout(() => controller.abort(), timeoutMs);
     if (options.signal)
         options.signal.addEventListener("abort", () => controller.abort(), { once: true });
-    const headers = { accept: "application/json" };
+    const headers = {
+        accept: options.as === "text" ? "text/plain, text/markdown, */*" : "application/json",
+    };
     if (body !== undefined)
         headers["content-type"] = "application/json";
     if (token !== undefined && token.length > 0)
@@ -247,8 +121,12 @@ async function once(base, path, options) {
         clearTimeout(deadline);
     }
     const text = await response.text();
+    // ⛔ A TEXT ANSWER IS ONLY TEXT WHEN THE SERVER AGREED. A refusal is JSON however the request
+    //    asked, so a failing document fetch still goes through the reading below and still reaches
+    //    the caller as a named refusal rather than as a page of HTML pretending to be a notice.
+    const asText = options.as === "text" && response.ok;
     let parsed = null;
-    if (text.length > 0) {
+    if (text.length > 0 && !asText) {
         try {
             parsed = JSON.parse(text);
         }
@@ -261,11 +139,30 @@ async function once(base, path, options) {
             });
         }
     }
+    // ⛔ The run log's one hook: here, where the outcome is known and nothing has yet been thrown.
+    noteRequest(method, path, response.status, isRefusal(parsed) ? parsed.error.message : undefined);
     if (!response.ok) {
         if (isRefusal(parsed)) {
-            throw new ServerError(response.status, parsed.error, adviseFor(parsed.error.code));
+            const wait = response.headers.get("retry-after");
+            throw new ServerError(response.status, parsed.error, adviseFor(parsed.error.code), wait !== null && /^\d+$/.test(wait.trim()) ? Number(wait) : null);
         }
-        throw new NmtsError(`${base} answered ${response.status}.`, { exitCode: 1 });
+        throw new HttpError(response.status, `${base} answered ${response.status}.`);
     }
+    if (asText)
+        return { text, filename: filenameFrom(response.headers.get("content-disposition")) };
     return parsed;
 }
+/**
+ * The file name a `Content-Disposition` header gives a body, or null when it names none.
+ *
+ * ⛔ THE LAST SEGMENT AND NOTHING ELSE. This value came over the network and is on its way to a
+ *    name on somebody's disk. `safe-path.ts` contains it as well, and this is the first of the
+ *    two: a header saying `filename="../../etc/passwd"` must not survive even as far as being
+ *    joined to a directory. Anything that reduces to nothing, `.` or `..` is treated as no name
+ *    at all, which the caller answers by refusing rather than by inventing one.
+ */
+function filenameFrom(header) {
+    const quoted = header === null ? null : /filename="([^"]*)"/u.exec(header);
+    const name = (quoted?.[1] ?? "").split(/[/\\]/u).at(-1) ?? "";
+    return name === "" || name === "." || name === ".." ? null : name;
+}