@hardfin/cli 0.1.1-dev.55 → 0.1.1-dev.57

package/README.md

@@ -72,6 +72,19 @@ A value is sent as the type the document names. `--useful-life 36` sends the num
 decimal such as `--salvage-value 1500.00` stays a string, which is how the API takes money
 without losing precision.
 
+Inside a `key=value` flag, `=` gives a value as you typed it and `:=` gives it as JSON.
+
+| You type                | Is sent as                                                         |
+| ----------------------- | ------------------------------------------------------------------ |
+| `value=36`              | the text "36", because a custom field may hold a serial number     |
+| `value:=36`             | the number 36                                                      |
+| `value:=true`           | the boolean true                                                   |
+| `deliverAt:=null`       | null                                                               |
+| `order=2` or `order:=2` | the number 2, because the document types `order` as a whole number |
+
+A value the field does not take fails locally with exit code 2, such as `order=two`, or
+`id:=42` for a field that takes text alone.
+
 A download is written where you name it, and a terminal is never filled with a file's bytes.
 With no `--output`, the file takes the name it was uploaded under, in the working directory.
 That name never chooses a folder, a hidden file, or a file that is already there. The command
@@ -130,6 +143,31 @@ An agent branches on `code`. A code is never renamed and never changes meaning,
 message may be reworded at any time. `hardfin agent-guide` lists every code with what it
 means, and `src/output/failure.ts` defines them.
 
+### Calling an endpoint no command covers
+
+`hardfin api` calls any path under the API. It takes the same parts a generated command does,
+named by hand.
+
+```sh
+hardfin api /customer -f page=2 -f limit=50                    # query parameters
+hardfin api -X PATCH /item/item_V1StGXR8Z5jdHi6B --input body.json   # a JSON body
+hardfin api /file/file_7hq2mx9pkr4stz8w --output photo.jpg      # a download
+hardfin api -X POST /file --file photo.jpg -F fileType=ASSET_FILE   # an upload, as multipart
+hardfin api /file/file_7hq2mx9pkr4stz8w -H 'If-None-Match: "abc"' --output photo.jpg
+```
+
+| Flag               | Sends                                                                              |
+| ------------------ | ---------------------------------------------------------------------------------- |
+| `-f key=value`     | A query parameter, repeatable                                                      |
+| `--input <path>`   | A JSON body, from a file or `-` for standard input                                 |
+| `--file <path>`    | A file as multipart, under the part name `data` unless `--file-part` names another |
+| `-F key=value`     | A field beside the file, repeatable                                                |
+| `-H "Name: value"` | A request header, repeatable                                                       |
+| `--output <path>`  | Nothing. It writes the file the endpoint answers with, or `-` for standard output  |
+
+A header cannot set `Authorization`, `X-API-Key` or `X-API-Version`, which come from your sign
+in and settings. `--file` and `--input` cannot be given together.
+
 ### Reading the commands from a program
 
 `hardfin agent-guide` describes the CLI to an agent, as Markdown or as JSON. Name a command to

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c6243d33-fcd1-5df5-9405-f1e6448344d6")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1c7d3a24-925a-543e-a2eb-caf5f5968ada")}catch(e){}}();
 import module from "node:module";
 //#region src/cli.ts
 module.enableCompileCache?.();
@@ -14,7 +14,7 @@ process.on("unhandledRejection", (error) => void toCrash(error));
 try {
 	const answer = await toQuickAnswer(process.argv.slice(2));
 	if (answer === void 0) {
-		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-BhH7Zc0y.js");
+		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-PaNgBWFL.js");
 		try {
 			await toCli().parseAsync(process.argv);
 		} catch (error) {
@@ -33,7 +33,7 @@ async function toCrash(error) {
 	isCrashing = true;
 	const isJSON = process.argv.includes("--json") || !process.stdout.isTTY;
 	try {
-		const { toReported, writeCrash } = await import("./program-BhH7Zc0y.js");
+		const { toReported, writeCrash } = await import("./program-PaNgBWFL.js");
 		writeCrash(error, isJSON);
 		await toReported(error, isJSON, void 0, "fatal");
 	} catch {
@@ -54,4 +54,4 @@ async function toQuickAnswer(args) {
 export {};
 
 //# sourceMappingURL=cli.js.map
-//# debugId=c6243d33-fcd1-5df5-9405-f1e6448344d6
+//# debugId=1c7d3a24-925a-543e-a2eb-caf5f5968ada

package/dist/completion-tree.json

@@ -2566,6 +2566,35 @@
           "description": "A file holding the JSON request body, or - for stdin",
           "valueName": "file"
         },
+        {
+          "name": "file",
+          "description": "A file to upload as multipart, in place of a JSON body",
+          "valueName": "path"
+        },
+        {
+          "name": "file-part",
+          "description": "The name of the part the file is sent as, which is data when not given",
+          "valueName": "name"
+        },
+        {
+          "name": "form",
+          "short": "F",
+          "description": "A field sent beside the file as key=value, repeatable",
+          "valueName": "key=value",
+          "repeatable": true
+        },
+        {
+          "name": "header",
+          "short": "H",
+          "description": "A request header as Name: value, repeatable",
+          "valueName": "name: value",
+          "repeatable": true
+        },
+        {
+          "name": "output",
+          "description": "Where to write a file the endpoint answers with, or - for standard output",
+          "valueName": "path"
+        },
         {
           "name": "json",
           "description": "Print machine-readable output, which is the default when stdout is not a terminal"

package/dist/{program-BhH7Zc0y.js → program-PaNgBWFL.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="91a42949-4ebc-5767-bd2f-75c98f7b5603")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="566d9b65-d8fb-507d-8b0e-a21deb646246")}catch(e){}}();
 import { a as defineCommand, i as GLOBAL_FLAGS, r as ExitCode, t as toInvocation } from "./scrub-BZ0egWxC.js";
 import { n as toAnswer$1, r as toCompletion, t as PATH_VALUES } from "./completion-tree-DLC6ARLR.js";
 import { createRequire } from "node:module";
@@ -1127,6 +1127,7 @@ async function request$1(options) {
 	const url = new URL(`${options.apiUrl}${toLeadingSlash(options.path)}`);
 	for (const [name, value] of options.query ?? []) url.searchParams.append(name, value);
 	const headers = {
+		...options.headers,
 		[options.credential.header]: options.credential.value,
 		"X-API-Version": API_VERSION,
 		Accept: options.downloads ? "*/*" : "application/json"
@@ -1477,7 +1478,8 @@ function toDescribed(flag) {
 		default: flag.defaultValue,
 		schema: toFlagSchema(flag),
 		sends: sent.queryName !== void 0 ? { query: sent.queryName } : sent.jsonPath !== void 0 ? { body: sent.jsonPath } : void 0,
-		element: sent.element
+		element: sent.element,
+		elementTypes: sent.elementTypes
 	};
 	return Object.fromEntries(Object.entries(described).filter(([, value]) => value !== void 0 && value !== false));
 }
@@ -1557,10 +1559,363 @@ function toJSONInput(source) {
 		return new InputFailure(`${name} does not hold JSON`);
 	}
 }
+//#endregion
+//#region src/command/operation.ts
+/**
+* toEnum takes a value in any case, as the API does, and answers the spelling the document
+* lists, which is what a response always uses.
+*/
+function toEnum(values) {
+	return z.string().transform((value) => values.find((allowed) => allowed.toLowerCase() === value.toLowerCase()) ?? value).pipe(z.enum(values));
+}
+const UNSET_FLAG = {
+	name: "unset",
+	description: "A field to clear, named as its flag is, repeatable",
+	valueName: "field",
+	repeatable: true,
+	schema: z.array(z.string())
+};
+const INPUT_FLAG = {
+	name: "input",
+	description: "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
+	valueName: "path",
+	schema: z.string()
+};
+const FILE_FLAG = {
+	name: "file",
+	description: "The file to upload",
+	valueName: "path",
+	schema: z.string()
+};
+const OUTPUT_FLAG = {
+	name: "output",
+	description: "Where to write the file, or - for standard output",
+	valueName: "path",
+	schema: z.string()
+};
+const JSON_FLAG$1 = {
+	name: "json",
+	description: "Print machine-readable output, which is the default when stdout is not a terminal",
+	schema: z.boolean()
+};
+/** defineOperation turns one endpoint into the command that calls it. */
+function defineOperation(operation) {
+	const flags = [
+		...operation.queryFlags,
+		...operation.bodyFlags,
+		...operation.bodyFlags.some((flag) => flag.nullable) ? [UNSET_FLAG] : [],
+		...operation.bodyFlags.length > 0 ? [INPUT_FLAG] : [],
+		...operation.upload ? [...operation.upload.fields, FILE_FLAG] : [],
+		...operation.downloads ? [OUTPUT_FLAG] : [],
+		JSON_FLAG$1
+	];
+	return {
+		name: operation.name,
+		summary: operation.summary,
+		description: operation.description ?? operation.summary,
+		arguments: operation.pathParameters,
+		flags,
+		examples: operation.example ? [{
+			description: operation.summary,
+			command: operation.example
+		}] : [],
+		endpoint: {
+			method: operation.method,
+			path: operation.path
+		},
+		run: (input) => runOperation(operation, input)
+	};
+}
+async function runOperation(operation, input) {
+	const path = toPath(operation, input.args);
+	if (path === void 0) {
+		writeFailure("invalid_arguments", `this command takes ${operation.pathParameters.length} argument(s), each the key of a record`, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const given = toGivenBody$1(input.flags["input"]);
+	if (given instanceof InputFailure) {
+		writeFailure("invalid_input", given.message, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const missing = operation.bodyFlags.concat(operation.upload?.fields ?? []).filter((flag) => flag.required && input.flags[toOptionKey(flag.name)] === void 0 && !hasPath(given, flag.jsonPath));
+	if (missing.length > 0) {
+		writeFailure("missing_flag", `this command needs ${missing.map((flag) => `--${flag.name}`).join(", ")}`, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const body = toBody(operation, input.flags, given);
+	if (body instanceof Error) {
+		writeFailure("invalid_flag", body.message, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	if (operation.bodyFlags.length > 0 && body === void 0) {
+		writeFailure("empty_request", `this command changes nothing unless a flag is given, such as ${operation.bodyFlags.slice(0, 3).map((flag) => `--${flag.name}`).join(", ")}. Run it with --help for the rest`, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	let form;
+	if (operation.upload) {
+		const built = await toForm$1(operation.upload, input.flags);
+		if (built instanceof Error) {
+			writeFailure("invalid_input", built.message, input.isJSON);
+			return ExitCode.USAGE;
+		}
+		form = built;
+	}
+	try {
+		const envelope = await request$1({
+			apiUrl: input.resolved.settings.apiUrl,
+			credential: await toRequestCredential(input.resolved.settings, input.resolved.sources),
+			method: operation.method,
+			path,
+			query: toQuery$1(operation, input.flags),
+			body,
+			form,
+			downloads: operation.downloads
+		});
+		if (operation.downloads) return toWritten(envelope.data, input);
+		writeData(envelope.data);
+		return ExitCode.OK;
+	} catch (error) {
+		if (error instanceof NoCredential) {
+			writeFailure("not_signed_in", error.message, input.isJSON);
+			return ExitCode.NOT_AUTHENTICATED;
+		}
+		if (error instanceof RequestFailure) {
+			writeFailure(toRequestCode(error), error.message, input.isJSON, error.errors, error.requestId, error.status);
+			return error.status === 401 ? ExitCode.NOT_AUTHENTICATED : ExitCode.ERROR;
+		}
+		throw error;
+	}
+}
+/**
+* toWritten puts a downloaded file where it was asked for. A terminal is never written to,
+* because a person would otherwise have their session filled with a file's bytes.
+*/
+function toWritten(download, input) {
+	const asked = input.flags["output"];
+	const offered = typeof asked === "string" ? void 0 : download.fileName;
+	const path = typeof asked === "string" ? asked : offered === void 0 ? "-" : toLocalName(offered);
+	if (path === void 0 || offered !== void 0 && existsSync(path)) {
+		writeFailure("output_required", path === void 0 ? `this file is offered as ${JSON.stringify(offered)}, which is not a name to write here, so name where to write it with --output` : `${path} already exists, so name where to write this file with --output`, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	if (path === "-") {
+		if (process.stdout.isTTY) {
+			writeFailure("output_required", "this answer is a file, so name where to write it with --output, or send it on with a pipe", input.isJSON);
+			return ExitCode.USAGE;
+		}
+		process.stdout.write(download.bytes);
+		return ExitCode.OK;
+	}
+	writeFileSync(path, download.bytes);
+	writeData({
+		written: path,
+		bytes: download.bytes.length,
+		contentType: download.contentType
+	});
+	return ExitCode.OK;
+}
+/** toLocalName reduces a name the API offered to one file in the working directory, or to nothing. */
+function toLocalName(offered) {
+	const name = offered.split(/[\\/]/).pop() ?? "";
+	return name === "" || name.startsWith(".") ? void 0 : name;
+}
+/** The arguments a URL reads as "this folder" and "the one above", and one that names nothing. */
+const NOT_A_KEY = /* @__PURE__ */ new Set([
+	"",
+	".",
+	".."
+]);
+/** toPath fills the path template from the positional arguments, in order. */
+function toPath(operation, args) {
+	if (args.length !== operation.pathParameters.length || args.some((argument) => NOT_A_KEY.has(argument))) return;
+	let path = operation.path;
+	for (const [index, parameter] of operation.pathParameters.entries()) path = path.replace(`{${parameter.name}}`, encodeURIComponent(args[index] ?? ""));
+	return path;
+}
+/** toQuery carries only the flags this invocation actually set. */
+function toQuery$1(operation, flags) {
+	const query = new URLSearchParams();
+	for (const flag of operation.queryFlags) {
+		const value = flags[toOptionKey(flag.name)];
+		if (value === void 0) continue;
+		const parsed = flag.schema.safeParse(value);
+		const carried = parsed.success ? parsed.data : value;
+		for (const entry of Array.isArray(carried) ? carried : [carried]) query.append(flag.queryName, toText(entry));
+	}
+	return query;
+}
+/** toOptionKey names the parsed flag, which the parser reports in camel case. */
+function toOptionKey(name) {
+	return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+/** toForm builds the file part and its fields, which an upload endpoint takes. */
+async function toForm$1(upload, flags) {
+	const path = flags["file"];
+	if (typeof path !== "string") return /* @__PURE__ */ new Error("this command needs --file, the file to upload");
+	const form = new FormData();
+	try {
+		form.append(upload.filePart, await openAsBlob(path), basename(path));
+	} catch {
+		return /* @__PURE__ */ new Error(`${path} cannot be read`);
+	}
+	for (const field of upload.fields) {
+		const value = flags[toOptionKey(field.name)];
+		if (value !== void 0) {
+			const parsed = field.schema.safeParse(value);
+			form.append(field.jsonPath[0] ?? field.name, toText(parsed.success ? parsed.data : value));
+		}
+	}
+	return form;
+}
+/** toGivenBody reads the --input body, which a generated command takes only as a JSON object. */
+function toGivenBody$1(source) {
+	if (typeof source !== "string") return;
+	const read = toJSONInput(source);
+	if (read instanceof InputFailure) return read;
+	if (typeof read !== "object" || read === null || Array.isArray(read)) return new InputFailure(`the body in ${source === "-" ? "standard input" : source} must be a JSON object, such as {"name": "Acme"}`);
+	return read;
+}
+/** hasPath reports whether a body already holds a value at a field's path. */
+function hasPath(body, path) {
+	let holder = body;
+	for (const name of path) {
+		if (typeof holder !== "object" || holder === null || !(name in holder)) return false;
+		holder = holder[name];
+	}
+	return true;
+}
+/** toBody builds the request body from the --input body and the flags, a flag winning over its field. */
+function toBody(operation, flags, given) {
+	const body = given ? structuredClone(given) : {};
+	let hasField = given !== void 0;
+	for (const flag of operation.bodyFlags) {
+		const value = flags[toOptionKey(flag.name)];
+		if (value === void 0) continue;
+		if (flag.element) {
+			const elements = toElements(flag, Array.isArray(value) ? value.map(toText) : [toText(value)]);
+			if (elements instanceof Error) return elements;
+			set(body, flag.jsonPath, elements);
+			hasField = true;
+			continue;
+		}
+		const parsed = flag.schema.safeParse(value);
+		set(body, flag.jsonPath, parsed.success ? parsed.data : value);
+		hasField = true;
+	}
+	const cleared = toCleared(operation, flags, body);
+	if (cleared instanceof Error) return cleared;
+	return hasField || cleared ? body : void 0;
+}
+/** toCleared sends null for each field named by --unset, which is how a field is cleared. */
+function toCleared(operation, flags, body) {
+	const named = flags["unset"];
+	const names = Array.isArray(named) ? named.map(toText) : named === void 0 ? [] : [toText(named)];
+	for (const name of names) {
+		const flag = operation.bodyFlags.find((entry) => entry.name === name.replace(/^--/, ""));
+		if (!flag) return /* @__PURE__ */ new Error(`--unset names no field called ${name}`);
+		if (!flag.nullable) return /* @__PURE__ */ new Error(`--${flag.name} cannot be cleared, because the API does not accept null for it`);
+		set(body, flag.jsonPath, null);
+	}
+	return names.length > 0;
+}
+/** toElements reads the key=value pairs a repeated flag carries for one array element. */
+function toElements(flag, values) {
+	const elements = [];
+	for (const value of values) {
+		const element = {};
+		for (const pair of value.split(",")) {
+			const split = pair.indexOf("=");
+			if (split < 1) return /* @__PURE__ */ new Error(`--${flag.name} takes ${flag.element?.join("=, ") ?? ""}=, such as --${flag.name} ${flag.element?.[0] ?? "field"}=value. A value cannot contain a comma`);
+			const isJSON = pair[split - 1] === ":";
+			const key = pair.slice(0, isJSON ? split - 1 : split).trim();
+			if (flag.element && !flag.element.includes(key)) return /* @__PURE__ */ new Error(`--${flag.name} has no field ${key}. It takes ${flag.element.join(", ")}`);
+			if (key in element) return /* @__PURE__ */ new Error(`--${flag.name} names ${key} twice in one element, so which one it takes is not clear`);
+			const value = pair.slice(split + 1).trim();
+			if (flag.elementUuids?.includes(key) && !z.uuid().safeParse(value).success) return /* @__PURE__ */ new Error(`--${flag.name} needs a UUID for ${key}, such as 3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90, and ${value || "nothing"} is not one`);
+			const types = flag.elementTypes?.[key];
+			const typed = isJSON ? toJSONValue(value, types ?? ["string"]) : toTyped(value, types);
+			if (typed === NOT_TAKEN) return /* @__PURE__ */ new Error(`--${flag.name} needs ${toNamedTypes(types ?? ["string"])} for ${key}, and ${value || "nothing"} is not one`);
+			element[key] = typed;
+		}
+		elements.push(element);
+	}
+	return elements;
+}
+/** Marks text that is none of the types a field takes. */
+const NOT_TAKEN = Symbol("not taken");
+const NUMBER = /^-?\d+(\.\d+)?$/;
+/**
+* toTyped reads the text after key= as the type the document gives the field. A field that
+* takes text is sent as typed, whatever it looks like, because 36 may be a serial number. A
+* field that takes no text has only one reading, so order=2 is sent as the number.
+*/
+function toTyped(text, types) {
+	if (types === void 0 || types.includes("string")) return text;
+	if (types.includes("null") && text === "null") return null;
+	if ((types.includes("integer") || types.includes("number")) && NUMBER.test(text)) {
+		const value = Number(text);
+		if (types.includes("number") || Number.isInteger(value)) return value;
+	}
+	if (types.includes("boolean") && (text === "true" || text === "false")) return text === "true";
+	return NOT_TAKEN;
+}
+/**
+* toJSONValue reads the text after key:= as JSON, and takes it when the field takes its type.
+* It is how a custom field is given the number 36 or true, where key= would send the text.
+*/
+function toJSONValue(text, types) {
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return NOT_TAKEN;
+	}
+	const type = value === null ? "null" : typeof value;
+	return (types.includes(type) || type === "number" && types.includes("integer") && Number.isInteger(value)) && type !== "object" ? value : NOT_TAKEN;
+}
+/** toNamedTypes says in words what a field takes, for the message that refuses a value. */
+function toNamedTypes(types) {
+	const named = {
+		integer: "a whole number",
+		number: "a number",
+		boolean: "true or false",
+		string: "text in quotes",
+		null: "null"
+	};
+	return types.filter((type) => type in named).map((type) => named[type]).join(" or ");
+}
+/** set writes a value at its path, building the objects a nested field needs. */
+function set(body, path, value) {
+	let holder = body;
+	for (const name of path.slice(0, -1)) {
+		holder[name] = holder[name] ?? {};
+		holder = holder[name];
+	}
+	holder[path[path.length - 1] ?? ""] = value;
+}
+//#endregion
+//#region src/command/api.ts
+const METHODS = [
+	"GET",
+	"POST",
+	"PATCH",
+	"PUT",
+	"DELETE"
+];
+/** The part name the API's upload endpoints take a file under. */
+const DEFAULT_FILE_PART = "data";
+/** The headers that carry the credential and the version, which the CLI sets and a caller does not. */
+const KEPT_HEADERS = /* @__PURE__ */ new Set([
+	"authorization",
+	"x-api-key",
+	"x-api-version",
+	"host",
+	"content-length"
+]);
 const apiCommand = defineCommand({
 	name: "api",
 	summary: "Call a Hardfin API endpoint and print what it answers",
-	description: "Reaches every endpoint the API publishes. The path is everything after /v2, and the response envelope is printed as it arrived.",
+	description: "Reaches every endpoint the API publishes, for when no generated command fits. The path is everything after /v2, and what the endpoint answered with is printed. A file is uploaded with --file and downloaded with --output.",
 	arguments: [{
 		name: "path",
 		description: "The endpoint path, such as /customer or /item/item_V1StGXR8Z5jdHi6B",
@@ -1572,13 +1927,7 @@ const apiCommand = defineCommand({
 			short: "X",
 			description: "The HTTP method to use",
 			valueName: "method",
-			schema: z.enum([
-				"GET",
-				"POST",
-				"PATCH",
-				"PUT",
-				"DELETE"
-			]),
+			schema: z.enum(METHODS),
 			defaultValue: "GET"
 		},
 		{
@@ -1595,6 +1944,40 @@ const apiCommand = defineCommand({
 			valueName: "file",
 			schema: z.string().optional()
 		},
+		{
+			name: "file",
+			description: "A file to upload as multipart, in place of a JSON body",
+			valueName: "path",
+			schema: z.string().optional()
+		},
+		{
+			name: "file-part",
+			description: `The name of the part the file is sent as, which is ${DEFAULT_FILE_PART} when not given`,
+			valueName: "name",
+			schema: z.string().optional()
+		},
+		{
+			name: "form",
+			short: "F",
+			description: "A field sent beside the file as key=value, repeatable",
+			valueName: "key=value",
+			repeatable: true,
+			schema: z.array(z.string()).default([])
+		},
+		{
+			name: "header",
+			short: "H",
+			description: "A request header as Name: value, repeatable",
+			valueName: "name: value",
+			repeatable: true,
+			schema: z.array(z.string()).default([])
+		},
+		{
+			name: "output",
+			description: "Where to write a file the endpoint answers with, or - for standard output",
+			valueName: "path",
+			schema: z.string().optional()
+		},
 		{
 			name: "json",
 			description: "Print machine-readable output, which is the default when stdout is not a terminal",
@@ -1613,6 +1996,18 @@ const apiCommand = defineCommand({
 		{
 			description: "Change an item",
 			command: "hardfin api -X PATCH /item/item_V1StGXR8Z5jdHi6B --input body.json"
+		},
+		{
+			description: "Download a file",
+			command: "hardfin api /file/file_7hq2mx9pkr4stz8w --output photo.jpg"
+		},
+		{
+			description: "Upload a file, with the fields the endpoint takes beside it",
+			command: "hardfin api -X POST /file --file photo.jpg -F fileType=ASSET_FILE -F forEntity=0192f7d4-3b6a-7c1e-9f2d-5a8b4c6e7d70"
+		},
+		{
+			description: "Send a header",
+			command: "hardfin api /file/file_7hq2mx9pkr4stz8w -H \"If-None-Match: \\\"abc\\\"\" --output photo.jpg"
 		}
 	],
 	run: runApi
@@ -1627,11 +2022,22 @@ async function runApi(input) {
 		writeFailure("invalid_arguments", "a path stays inside the API, so it cannot climb out of it with ..", input.isJSON);
 		return ExitCode.USAGE;
 	}
-	const query = toQuery$1(input.flags["field"]);
+	const query = toQuery(input.flags["field"]);
 	if (query === void 0) {
 		writeFailure("invalid_flag", "each --field is key=value, such as -f limit=50", input.isJSON);
 		return ExitCode.USAGE;
 	}
+	const headers = toHeaders(input.flags["header"]);
+	if (headers instanceof Error) {
+		writeFailure("invalid_flag", headers.message, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const method = toText(input.flags["method"] ?? "GET").toUpperCase();
+	const isUpload = typeof input.flags["file"] === "string";
+	if (isUpload && (typeof input.flags["input"] === "string" || method === "GET")) {
+		writeFailure("invalid_flag", method === "GET" ? "--file uploads a file, so give the method with -X, such as -X POST" : "--file and --input both give the body, so give one of them", input.isJSON);
+		return ExitCode.USAGE;
+	}
 	let body;
 	if (typeof input.flags["input"] === "string") {
 		body = toJSONInput(input.flags["input"]);
@@ -1640,15 +2046,26 @@ async function runApi(input) {
 			return ExitCode.USAGE;
 		}
 	}
+	const form = isUpload ? await toForm(input.flags) : void 0;
+	if (form instanceof Error) {
+		writeFailure("invalid_input", form.message, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const isDownload = typeof input.flags["output"] === "string";
 	try {
-		writeData((await request$1({
+		const envelope = await request$1({
 			apiUrl: input.resolved.settings.apiUrl,
 			credential: await toRequestCredential(input.resolved.settings, input.resolved.sources),
-			method: toText(input.flags["method"] ?? "GET").toUpperCase(),
+			method,
 			path,
 			query,
-			body
-		})).data);
+			body,
+			form,
+			headers,
+			downloads: isDownload
+		});
+		if (isDownload) return toWritten(envelope.data, input);
+		writeData(envelope.data);
 		return ExitCode.OK;
 	} catch (error) {
 		if (error instanceof NoCredential) {
@@ -1670,11 +2087,39 @@ function isInsideApi(apiUrl, path) {
 		const root = base.pathname.replace(/\/+$/, "");
 		return target.origin === base.origin && (target.pathname === root || target.pathname.startsWith(`${root}/`));
 	} catch {
-		return false;
+		return false;
+	}
+}
+/** toHeaders reads the repeated --header flags, and refuses one the CLI sets itself. */
+function toHeaders(given) {
+	const headers = {};
+	for (const header of Array.isArray(given) ? given : []) {
+		const split = header.indexOf(":");
+		const name = header.slice(0, Math.max(split, 0)).trim();
+		if (split < 1 || !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name)) return /* @__PURE__ */ new Error(`--header is Name: value, such as -H "If-None-Match: abc", and ${JSON.stringify(header)} is not`);
+		if (KEPT_HEADERS.has(name.toLowerCase())) return /* @__PURE__ */ new Error(`--header cannot set ${name}, because the CLI sets it from your sign in and settings`);
+		headers[name] = header.slice(split + 1).trim();
+	}
+	return headers;
+}
+/** toForm builds the multipart body an upload sends: the file, and the fields given beside it. */
+async function toForm(flags) {
+	const path = toText(flags["file"]);
+	const form = new FormData();
+	try {
+		form.append(toText(flags["filePart"] ?? DEFAULT_FILE_PART), await openAsBlob(path), basename(path));
+	} catch {
+		return /* @__PURE__ */ new Error(`${path} cannot be read`);
+	}
+	for (const field of Array.isArray(flags["form"]) ? flags["form"] : []) {
+		const split = field.indexOf("=");
+		if (split < 1) return /* @__PURE__ */ new Error(`each --form is key=value, such as -F fileType=ASSET_FILE, and ${JSON.stringify(field)} is not`);
+		form.append(field.slice(0, split), field.slice(split + 1));
 	}
+	return form;
 }
 /** toQuery folds the repeated --field flags into query parameters. */
-function toQuery$1(fields) {
+function toQuery(fields) {
 	const query = new URLSearchParams();
 	for (const field of Array.isArray(fields) ? fields : []) {
 		const split = field.indexOf("=");
@@ -1932,7 +2377,7 @@ const YES_FLAG = {
 	description: "Make the change without asking",
 	schema: z.boolean()
 };
-const JSON_FLAG$1 = {
+const JSON_FLAG = {
 	name: "json",
 	description: "Print machine-readable output, which is the default when stdout is not a terminal",
 	schema: z.boolean()
@@ -1942,7 +2387,7 @@ const installCommand = defineCommand({
 	summary: "Set up completion in your shell",
 	description: "Writes the completion script under your data directory and loads it from your shell's startup file, between two marked lines. Fish loads it from its completions directory, so no startup file changes. Run it again after upgrading, so the script matches the CLI.",
 	arguments: [SHELL_ARGUMENT],
-	flags: [YES_FLAG, JSON_FLAG$1],
+	flags: [YES_FLAG, JSON_FLAG],
 	examples: [{
 		description: "Install for the shell you are using",
 		command: "hardfin completion install"
@@ -1957,7 +2402,7 @@ const uninstallCommand = defineCommand({
 	summary: "Remove completion from your shell",
 	description: "Removes the script install wrote, and the marked lines it added to your shell's startup file.",
 	arguments: [SHELL_ARGUMENT],
-	flags: [YES_FLAG, JSON_FLAG$1],
+	flags: [YES_FLAG, JSON_FLAG],
 	examples: [{
 		description: "Remove completion from zsh",
 		command: "hardfin completion uninstall zsh"
@@ -2962,419 +3407,132 @@ async function runDeviceLogin(input, metadata, scope) {
 	if (input.isJSON) writeEvent({
 		event: "device_code",
 		userCode: device.userCode,
-		verificationUri: device.verificationUri,
-		url,
-		browserOpened: opened,
-		waitSeconds: Math.max(0, Math.round((device.expiresAt - Date.now()) / 1e3))
-	});
-	else process.stderr.write([
-		"",
-		`  Code  ${toPrintable(device.userCode)}`,
-		`  At    ${toPrintable(device.verificationUri)}`,
-		"",
-		opened ? "Opened your browser there. Waiting for approval\n" : "Open that page on any machine, and enter the code. Waiting for approval\n"
-	].join("\n"));
-	const prompt = toPrompt(url);
-	try {
-		return await toSignedIn(input, metadata, await toDeviceTokens(toTokensFromDevice(metadata.token_endpoint, settings.clientId, device), prompt.pasted));
-	} finally {
-		prompt.close();
-	}
-}
-/**
-* toDeviceTokens waits for the approval, or for the keyboard. Ctrl-C arrives as an Interrupted
-* and stops quietly. Text followed by Enter means the person typed the code here, where it
-* does nothing, so they are told where it goes instead.
-*/
-async function toDeviceTokens(approved, typed) {
-	return await Promise.race([approved, typed.then(() => {
-		throw new SignInStopped("Sign in stopped. The code goes on the page in your browser, not here. Run hardfin login to try again.");
-	})]);
-}
-/** toSignedIn stores what a sign in issued, whichever flow issued it. */
-async function toSignedIn(input, metadata, tokens) {
-	const refreshToken = tokens.refreshToken;
-	if (!refreshToken) {
-		writeFailure("sign_in_failed", "the authorization server issued no refresh token, so this sign in cannot be kept", input.isJSON);
-		return ExitCode.ERROR;
-	}
-	const scopes = toGrantedScopes(tokens);
-	const backend = await withLock(() => keep$1(input.resolved.settings.issuerUrl, refreshToken, tokens.refreshExpiresAt, scopes));
-	if (input.isJSON) {
-		writeData({
-			signedIn: true,
-			issuer: metadata.issuer,
-			scope: tokens.scope ?? null,
-			scopes: scopes ?? null,
-			canWrite: toCanWrite(scopes),
-			storedIn: backend
-		});
-		return ExitCode.OK;
-	}
-	const stored = backend === "keyring" ? "your OS keyring" : toCredentialPath();
-	writeData([
-		`Signed in to ${metadata.issuer}`,
-		`Scope     ${scopes?.join(" ") ?? tokens.scope ?? "as granted"}`,
-		...toCanWrite(scopes) === false ? ["Access    read-only, so a command that changes a record will be refused"] : [],
-		`Stored in ${stored}`,
-		"",
-		"Run hardfin status to see what this CLI is using",
-		...isInstalled() ? [] : ["Run hardfin completion install to complete commands with Tab"]
-	].join("\n"));
-	return ExitCode.OK;
-}
-/** writeEvent tells a program what a sign in is waiting on, as one line of JSON on stderr. */
-function writeEvent(event) {
-	process.stderr.write(`${JSON.stringify(event)}\n`);
-}
-/** toAuthorizationUrl builds the URL the person approves this CLI at. */
-function toAuthorizationUrl(endpoint, request) {
-	const url = new URL(endpoint);
-	url.searchParams.set("response_type", "code");
-	url.searchParams.set("client_id", request.clientId);
-	url.searchParams.set("redirect_uri", request.redirectUri);
-	url.searchParams.set("scope", request.scope);
-	url.searchParams.set("state", request.state);
-	url.searchParams.set("code_challenge", request.challenge);
-	url.searchParams.set("code_challenge_method", "S256");
-	return url.toString();
-}
-//#endregion
-//#region src/command/logout.ts
-const logoutCommand = defineCommand({
-	name: "logout",
-	summary: "Sign out, and tell Hardfin to forget this machine",
-	description: "Removes the stored refresh token and asks the authorization server to revoke it, so a copy taken from this machine stops working.",
-	arguments: [],
-	flags: [{
-		name: "json",
-		description: "Print machine-readable output, which is the default when stdout is not a terminal",
-		schema: z.boolean()
-	}],
-	examples: [{
-		description: "Sign out",
-		command: "hardfin logout"
-	}],
-	run: runLogout
-});
-async function runLogout(input) {
-	const settings = input.resolved.settings;
-	const stored = toCredential(settings.issuerUrl);
-	if (!stored) {
-		writeData({
-			signedOut: false,
-			issuer: settings.issuerUrl,
-			reason: "no sign in was stored"
-		});
-		return ExitCode.OK;
-	}
-	let revoked = false;
-	try {
-		const metadata = await toMetadata(settings.issuerUrl);
-		if (metadata.revocation_endpoint) {
-			await revoke(metadata.revocation_endpoint, settings.clientId, stored.refreshToken);
-			revoked = true;
-		}
-	} catch {
-		revoked = false;
-	}
-	await withLock(() => {
-		forget(settings.issuerUrl);
-	});
-	forgetHeldTokens();
-	writeData({
-		signedOut: true,
-		issuer: settings.issuerUrl,
-		revoked
-	});
-	return ExitCode.OK;
-}
-//#endregion
-//#region src/command/operation.ts
-/**
-* toEnum takes a value in any case, as the API does, and answers the spelling the document
-* lists, which is what a response always uses.
-*/
-function toEnum(values) {
-	return z.string().transform((value) => values.find((allowed) => allowed.toLowerCase() === value.toLowerCase()) ?? value).pipe(z.enum(values));
-}
-const UNSET_FLAG = {
-	name: "unset",
-	description: "A field to clear, named as its flag is, repeatable",
-	valueName: "field",
-	repeatable: true,
-	schema: z.array(z.string())
-};
-const INPUT_FLAG = {
-	name: "input",
-	description: "A file holding the JSON request body, or - for standard input. A flag given as well replaces its field",
-	valueName: "path",
-	schema: z.string()
-};
-const FILE_FLAG = {
-	name: "file",
-	description: "The file to upload",
-	valueName: "path",
-	schema: z.string()
-};
-const OUTPUT_FLAG = {
-	name: "output",
-	description: "Where to write the file, or - for standard output",
-	valueName: "path",
-	schema: z.string()
-};
-const JSON_FLAG = {
-	name: "json",
-	description: "Print machine-readable output, which is the default when stdout is not a terminal",
-	schema: z.boolean()
-};
-/** defineOperation turns one endpoint into the command that calls it. */
-function defineOperation(operation) {
-	const flags = [
-		...operation.queryFlags,
-		...operation.bodyFlags,
-		...operation.bodyFlags.some((flag) => flag.nullable) ? [UNSET_FLAG] : [],
-		...operation.bodyFlags.length > 0 ? [INPUT_FLAG] : [],
-		...operation.upload ? [...operation.upload.fields, FILE_FLAG] : [],
-		...operation.downloads ? [OUTPUT_FLAG] : [],
-		JSON_FLAG
-	];
-	return {
-		name: operation.name,
-		summary: operation.summary,
-		description: operation.description ?? operation.summary,
-		arguments: operation.pathParameters,
-		flags,
-		examples: operation.example ? [{
-			description: operation.summary,
-			command: operation.example
-		}] : [],
-		endpoint: {
-			method: operation.method,
-			path: operation.path
-		},
-		run: (input) => runOperation(operation, input)
-	};
-}
-async function runOperation(operation, input) {
-	const path = toPath(operation, input.args);
-	if (path === void 0) {
-		writeFailure("invalid_arguments", `this command takes ${operation.pathParameters.length} argument(s), each the key of a record`, input.isJSON);
-		return ExitCode.USAGE;
-	}
-	const given = toGivenBody$1(input.flags["input"]);
-	if (given instanceof InputFailure) {
-		writeFailure("invalid_input", given.message, input.isJSON);
-		return ExitCode.USAGE;
-	}
-	const missing = operation.bodyFlags.concat(operation.upload?.fields ?? []).filter((flag) => flag.required && input.flags[toOptionKey(flag.name)] === void 0 && !hasPath(given, flag.jsonPath));
-	if (missing.length > 0) {
-		writeFailure("missing_flag", `this command needs ${missing.map((flag) => `--${flag.name}`).join(", ")}`, input.isJSON);
-		return ExitCode.USAGE;
-	}
-	const body = toBody(operation, input.flags, given);
-	if (body instanceof Error) {
-		writeFailure("invalid_flag", body.message, input.isJSON);
-		return ExitCode.USAGE;
-	}
-	if (operation.bodyFlags.length > 0 && body === void 0) {
-		writeFailure("empty_request", `this command changes nothing unless a flag is given, such as ${operation.bodyFlags.slice(0, 3).map((flag) => `--${flag.name}`).join(", ")}. Run it with --help for the rest`, input.isJSON);
-		return ExitCode.USAGE;
-	}
-	let form;
-	if (operation.upload) {
-		const built = await toForm(operation.upload, input.flags);
-		if (built instanceof Error) {
-			writeFailure("invalid_input", built.message, input.isJSON);
-			return ExitCode.USAGE;
-		}
-		form = built;
-	}
-	try {
-		const envelope = await request$1({
-			apiUrl: input.resolved.settings.apiUrl,
-			credential: await toRequestCredential(input.resolved.settings, input.resolved.sources),
-			method: operation.method,
-			path,
-			query: toQuery(operation, input.flags),
-			body,
-			form,
-			downloads: operation.downloads
-		});
-		if (operation.downloads) return toWritten(envelope.data, input);
-		writeData(envelope.data);
-		return ExitCode.OK;
-	} catch (error) {
-		if (error instanceof NoCredential) {
-			writeFailure("not_signed_in", error.message, input.isJSON);
-			return ExitCode.NOT_AUTHENTICATED;
-		}
-		if (error instanceof RequestFailure) {
-			writeFailure(toRequestCode(error), error.message, input.isJSON, error.errors, error.requestId, error.status);
-			return error.status === 401 ? ExitCode.NOT_AUTHENTICATED : ExitCode.ERROR;
-		}
-		throw error;
+		verificationUri: device.verificationUri,
+		url,
+		browserOpened: opened,
+		waitSeconds: Math.max(0, Math.round((device.expiresAt - Date.now()) / 1e3))
+	});
+	else process.stderr.write([
+		"",
+		`  Code  ${toPrintable(device.userCode)}`,
+		`  At    ${toPrintable(device.verificationUri)}`,
+		"",
+		opened ? "Opened your browser there. Waiting for approval\n" : "Open that page on any machine, and enter the code. Waiting for approval\n"
+	].join("\n"));
+	const prompt = toPrompt(url);
+	try {
+		return await toSignedIn(input, metadata, await toDeviceTokens(toTokensFromDevice(metadata.token_endpoint, settings.clientId, device), prompt.pasted));
+	} finally {
+		prompt.close();
 	}
 }
 /**
-* toWritten puts a downloaded file where it was asked for. A terminal is never written to,
-* because a person would otherwise have their session filled with a file's bytes.
+* toDeviceTokens waits for the approval, or for the keyboard. Ctrl-C arrives as an Interrupted
+* and stops quietly. Text followed by Enter means the person typed the code here, where it
+* does nothing, so they are told where it goes instead.
 */
-function toWritten(download, input) {
-	const asked = input.flags["output"];
-	const offered = typeof asked === "string" ? void 0 : download.fileName;
-	const path = typeof asked === "string" ? asked : offered === void 0 ? "-" : toLocalName(offered);
-	if (path === void 0 || offered !== void 0 && existsSync(path)) {
-		writeFailure("output_required", path === void 0 ? `this file is offered as ${JSON.stringify(offered)}, which is not a name to write here, so name where to write it with --output` : `${path} already exists, so name where to write this file with --output`, input.isJSON);
-		return ExitCode.USAGE;
+async function toDeviceTokens(approved, typed) {
+	return await Promise.race([approved, typed.then(() => {
+		throw new SignInStopped("Sign in stopped. The code goes on the page in your browser, not here. Run hardfin login to try again.");
+	})]);
+}
+/** toSignedIn stores what a sign in issued, whichever flow issued it. */
+async function toSignedIn(input, metadata, tokens) {
+	const refreshToken = tokens.refreshToken;
+	if (!refreshToken) {
+		writeFailure("sign_in_failed", "the authorization server issued no refresh token, so this sign in cannot be kept", input.isJSON);
+		return ExitCode.ERROR;
 	}
-	if (path === "-") {
-		if (process.stdout.isTTY) {
-			writeFailure("output_required", "this answer is a file, so name where to write it with --output, or send it on with a pipe", input.isJSON);
-			return ExitCode.USAGE;
-		}
-		process.stdout.write(download.bytes);
+	const scopes = toGrantedScopes(tokens);
+	const backend = await withLock(() => keep$1(input.resolved.settings.issuerUrl, refreshToken, tokens.refreshExpiresAt, scopes));
+	if (input.isJSON) {
+		writeData({
+			signedIn: true,
+			issuer: metadata.issuer,
+			scope: tokens.scope ?? null,
+			scopes: scopes ?? null,
+			canWrite: toCanWrite(scopes),
+			storedIn: backend
+		});
 		return ExitCode.OK;
 	}
-	writeFileSync(path, download.bytes);
-	writeData({
-		written: path,
-		bytes: download.bytes.length,
-		contentType: download.contentType
-	});
+	const stored = backend === "keyring" ? "your OS keyring" : toCredentialPath();
+	writeData([
+		`Signed in to ${metadata.issuer}`,
+		`Scope     ${scopes?.join(" ") ?? tokens.scope ?? "as granted"}`,
+		...toCanWrite(scopes) === false ? ["Access    read-only, so a command that changes a record will be refused"] : [],
+		`Stored in ${stored}`,
+		"",
+		"Run hardfin status to see what this CLI is using",
+		...isInstalled() ? [] : ["Run hardfin completion install to complete commands with Tab"]
+	].join("\n"));
 	return ExitCode.OK;
 }
-/** toLocalName reduces a name the API offered to one file in the working directory, or to nothing. */
-function toLocalName(offered) {
-	const name = offered.split(/[\\/]/).pop() ?? "";
-	return name === "" || name.startsWith(".") ? void 0 : name;
+/** writeEvent tells a program what a sign in is waiting on, as one line of JSON on stderr. */
+function writeEvent(event) {
+	process.stderr.write(`${JSON.stringify(event)}\n`);
 }
-/** The arguments a URL reads as "this folder" and "the one above", and one that names nothing. */
-const NOT_A_KEY = /* @__PURE__ */ new Set([
-	"",
-	".",
-	".."
-]);
-/** toPath fills the path template from the positional arguments, in order. */
-function toPath(operation, args) {
-	if (args.length !== operation.pathParameters.length || args.some((argument) => NOT_A_KEY.has(argument))) return;
-	let path = operation.path;
-	for (const [index, parameter] of operation.pathParameters.entries()) path = path.replace(`{${parameter.name}}`, encodeURIComponent(args[index] ?? ""));
-	return path;
+/** toAuthorizationUrl builds the URL the person approves this CLI at. */
+function toAuthorizationUrl(endpoint, request) {
+	const url = new URL(endpoint);
+	url.searchParams.set("response_type", "code");
+	url.searchParams.set("client_id", request.clientId);
+	url.searchParams.set("redirect_uri", request.redirectUri);
+	url.searchParams.set("scope", request.scope);
+	url.searchParams.set("state", request.state);
+	url.searchParams.set("code_challenge", request.challenge);
+	url.searchParams.set("code_challenge_method", "S256");
+	return url.toString();
 }
-/** toQuery carries only the flags this invocation actually set. */
-function toQuery(operation, flags) {
-	const query = new URLSearchParams();
-	for (const flag of operation.queryFlags) {
-		const value = flags[toOptionKey(flag.name)];
-		if (value === void 0) continue;
-		const parsed = flag.schema.safeParse(value);
-		const carried = parsed.success ? parsed.data : value;
-		for (const entry of Array.isArray(carried) ? carried : [carried]) query.append(flag.queryName, toText(entry));
+//#endregion
+//#region src/command/logout.ts
+const logoutCommand = defineCommand({
+	name: "logout",
+	summary: "Sign out, and tell Hardfin to forget this machine",
+	description: "Removes the stored refresh token and asks the authorization server to revoke it, so a copy taken from this machine stops working.",
+	arguments: [],
+	flags: [{
+		name: "json",
+		description: "Print machine-readable output, which is the default when stdout is not a terminal",
+		schema: z.boolean()
+	}],
+	examples: [{
+		description: "Sign out",
+		command: "hardfin logout"
+	}],
+	run: runLogout
+});
+async function runLogout(input) {
+	const settings = input.resolved.settings;
+	const stored = toCredential(settings.issuerUrl);
+	if (!stored) {
+		writeData({
+			signedOut: false,
+			issuer: settings.issuerUrl,
+			reason: "no sign in was stored"
+		});
+		return ExitCode.OK;
 	}
-	return query;
-}
-/** toOptionKey names the parsed flag, which the parser reports in camel case. */
-function toOptionKey(name) {
-	return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
-}
-/** toForm builds the file part and its fields, which an upload endpoint takes. */
-async function toForm(upload, flags) {
-	const path = flags["file"];
-	if (typeof path !== "string") return /* @__PURE__ */ new Error("this command needs --file, the file to upload");
-	const form = new FormData();
+	let revoked = false;
 	try {
-		form.append(upload.filePart, await openAsBlob(path), basename(path));
-	} catch {
-		return /* @__PURE__ */ new Error(`${path} cannot be read`);
-	}
-	for (const field of upload.fields) {
-		const value = flags[toOptionKey(field.name)];
-		if (value !== void 0) {
-			const parsed = field.schema.safeParse(value);
-			form.append(field.jsonPath[0] ?? field.name, toText(parsed.success ? parsed.data : value));
-		}
-	}
-	return form;
-}
-/** toGivenBody reads the --input body, which a generated command takes only as a JSON object. */
-function toGivenBody$1(source) {
-	if (typeof source !== "string") return;
-	const read = toJSONInput(source);
-	if (read instanceof InputFailure) return read;
-	if (typeof read !== "object" || read === null || Array.isArray(read)) return new InputFailure(`the body in ${source === "-" ? "standard input" : source} must be a JSON object, such as {"name": "Acme"}`);
-	return read;
-}
-/** hasPath reports whether a body already holds a value at a field's path. */
-function hasPath(body, path) {
-	let holder = body;
-	for (const name of path) {
-		if (typeof holder !== "object" || holder === null || !(name in holder)) return false;
-		holder = holder[name];
-	}
-	return true;
-}
-/** toBody builds the request body from the --input body and the flags, a flag winning over its field. */
-function toBody(operation, flags, given) {
-	const body = given ? structuredClone(given) : {};
-	let hasField = given !== void 0;
-	for (const flag of operation.bodyFlags) {
-		const value = flags[toOptionKey(flag.name)];
-		if (value === void 0) continue;
-		if (flag.element) {
-			const elements = toElements(flag, Array.isArray(value) ? value.map(toText) : [toText(value)]);
-			if (elements instanceof Error) return elements;
-			set(body, flag.jsonPath, elements);
-			hasField = true;
-			continue;
-		}
-		const parsed = flag.schema.safeParse(value);
-		set(body, flag.jsonPath, parsed.success ? parsed.data : value);
-		hasField = true;
-	}
-	const cleared = toCleared(operation, flags, body);
-	if (cleared instanceof Error) return cleared;
-	return hasField || cleared ? body : void 0;
-}
-/** toCleared sends null for each field named by --unset, which is how a field is cleared. */
-function toCleared(operation, flags, body) {
-	const named = flags["unset"];
-	const names = Array.isArray(named) ? named.map(toText) : named === void 0 ? [] : [toText(named)];
-	for (const name of names) {
-		const flag = operation.bodyFlags.find((entry) => entry.name === name.replace(/^--/, ""));
-		if (!flag) return /* @__PURE__ */ new Error(`--unset names no field called ${name}`);
-		if (!flag.nullable) return /* @__PURE__ */ new Error(`--${flag.name} cannot be cleared, because the API does not accept null for it`);
-		set(body, flag.jsonPath, null);
-	}
-	return names.length > 0;
-}
-/** toElements reads the key=value pairs a repeated flag carries for one array element. */
-function toElements(flag, values) {
-	const elements = [];
-	for (const value of values) {
-		const element = {};
-		for (const pair of value.split(",")) {
-			const split = pair.indexOf("=");
-			if (split < 1) return /* @__PURE__ */ new Error(`--${flag.name} takes ${flag.element?.join("=, ") ?? ""}=, such as --${flag.name} ${flag.element?.[0] ?? "field"}=value. A value cannot contain a comma`);
-			const key = pair.slice(0, split).trim();
-			if (flag.element && !flag.element.includes(key)) return /* @__PURE__ */ new Error(`--${flag.name} has no field ${key}. It takes ${flag.element.join(", ")}`);
-			if (key in element) return /* @__PURE__ */ new Error(`--${flag.name} names ${key} twice in one element, so which one it takes is not clear`);
-			const value = pair.slice(split + 1).trim();
-			if (flag.elementUuids?.includes(key) && !z.uuid().safeParse(value).success) return /* @__PURE__ */ new Error(`--${flag.name} needs a UUID for ${key}, such as 3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90, and ${value || "nothing"} is not one`);
-			element[key] = value;
+		const metadata = await toMetadata(settings.issuerUrl);
+		if (metadata.revocation_endpoint) {
+			await revoke(metadata.revocation_endpoint, settings.clientId, stored.refreshToken);
+			revoked = true;
 		}
-		elements.push(element);
-	}
-	return elements;
-}
-/** set writes a value at its path, building the objects a nested field needs. */
-function set(body, path, value) {
-	let holder = body;
-	for (const name of path.slice(0, -1)) {
-		holder[name] = holder[name] ?? {};
-		holder = holder[name];
+	} catch {
+		revoked = false;
 	}
-	holder[path[path.length - 1] ?? ""] = value;
+	await withLock(() => {
+		forget(settings.issuerUrl);
+	});
+	forgetHeldTokens();
+	writeData({
+		signedOut: true,
+		issuer: settings.issuerUrl,
+		revoked
+	});
+	return ExitCode.OK;
 }
 //#endregion
 //#region src/mcp/confine.ts
@@ -4826,6 +4984,12 @@ const commands = [
 									"destinationId",
 									"originId"
 								],
+								elementTypes: {
+									"deliverAt": ["string", "null"],
+									"deliverAtTimezone": ["string", "null"],
+									"shipAt": ["string", "null"],
+									"shipAtTimezone": ["string", "null"]
+								},
 								schema: z.array(z.string())
 							}]
 						})]
@@ -4856,6 +5020,10 @@ const commands = [
 									"shipAt"
 								],
 								elementUuids: ["assetId"],
+								elementTypes: {
+									"deliverAt": ["string", "null"],
+									"shipAt": ["string", "null"]
+								},
 								schema: z.array(z.string())
 							}]
 						})]
@@ -4933,6 +5101,14 @@ const commands = [
 							repeatable: true,
 							element: ["fieldId", "value"],
 							elementUuids: ["fieldId"],
+							elementTypes: { "value": [
+								"array",
+								"boolean",
+								"number",
+								"object",
+								"string",
+								"null"
+							] },
 							schema: z.array(z.string())
 						},
 						{
@@ -6277,6 +6453,10 @@ const commands = [
 								"section"
 							],
 							elementUuids: ["fieldId"],
+							elementTypes: {
+								"order": ["integer"],
+								"section": ["integer"]
+							},
 							schema: z.array(z.string())
 						},
 						{
@@ -7177,5 +7357,5 @@ async function toReported(error, isJSON, resolved, level = "error") {
 //#endregion
 export { toCli, toParseExitCode, toReported, wasReportAttempted, writeCrash };
 
-//# sourceMappingURL=program-BhH7Zc0y.js.map
-//# debugId=91a42949-4ebc-5767-bd2f-75c98f7b5603
+//# sourceMappingURL=program-PaNgBWFL.js.map
+//# debugId=566d9b65-d8fb-507d-8b0e-a21deb646246

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hardfin/cli",
-    "version": "0.1.1-dev.55",
+    "version": "0.1.1-dev.57",
     "description": "Command line interface for the Hardfin API",
     "license": "Apache-2.0",
     "author": "Hardfin, Inc.",