@hardfin/cli 0.1.0-dev.35 → 0.1.0-dev.37

package/README.md

@@ -307,6 +307,44 @@ show a description beside each.
 The script calls `hardfin` by name, so it needs `hardfin` on your `PATH`. Running
 `node dist/cli.js` from a checkout leaves nothing for it to call, and `npm link` fixes that.
 
+## Types for code that calls the API
+
+```sh
+hardfin types --output src/hardfin-api.d.ts
+```
+
+`hardfin types` prints a TypeScript declaration for every record the API sends and takes,
+plus `ApiEnvelope<T>` for the response wrapper. The declarations are generated from the
+vendored API document by `scripts/generate-surface.mjs`, alongside the commands, so they
+match the API version this CLI calls. CI fails a pull request whose generated commands or
+types are stale.
+
+## Setting up a project for agents
+
+```sh
+hardfin init            # the working directory
+hardfin init --dry-run  # what it would write, writing nothing
+```
+
+`hardfin init` gets a project ready for a coding agent to use Hardfin, the way EmDash's starter
+projects come ready. Running it again updates only what it wrote.
+
+| File                                  | What init writes                                                    |
+| ------------------------------------- | ------------------------------------------------------------------- |
+| `.agents/skills/hardfin-cli/SKILL.md` | The `hardfin-cli` skill, which Codex and most agents read           |
+| `.claude/skills/hardfin-cli/SKILL.md` | The same skill, where Claude Code reads it                          |
+| `AGENTS.md`                           | A Hardfin section between `hardfin:start` and `hardfin:end` markers |
+| `.mcp.json`                           | The `hardfin` server, for Claude Code                               |
+| `.cursor/mcp.json`                    | The `hardfin` server, for Cursor                                    |
+| `.vscode/mcp.json`                    | The `hardfin` server, for VS Code                                   |
+
+The server is the hosted one at the authorization server's host, `https://api.hardfin.com/mcp`
+by default. Every other server in an MCP config, and everything in `AGENTS.md` outside the
+markers, is left as it was. A config that does not hold JSON is skipped, never overwritten.
+
+The skill lives in `skills/` and the section in `templates/AGENTS.md`. Both ship in the npm
+package, so `init` writes the copy that matches the installed CLI.
+
 ## Serving an agent
 
 ```sh

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]="e0ebce65-52b6-5732-b4b2-1becfe72bdef")}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]="b1580db0-6822-5a25-b000-03705726eaf6")}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-BdRDIa3u.js");
+		const { toCli, toParseExitCode, wasReportAttempted } = await import("./program-CjKwnPeY.js");
 		try {
 			await toCli().parseAsync(process.argv);
 		} catch (error) {
@@ -33,7 +33,7 @@ async function toCrash(error) {
 	isCrashing = true;
 	process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}\n`);
 	try {
-		const { toReported } = await import("./program-BdRDIa3u.js");
+		const { toReported } = await import("./program-CjKwnPeY.js");
 		await toReported(error, false, void 0, "fatal");
 	} finally {
 		process.exit(1);
@@ -51,4 +51,4 @@ async function toQuickAnswer(args) {
 export {};
 
 //# sourceMappingURL=cli.js.map
-//# debugId=e0ebce65-52b6-5732-b4b2-1becfe72bdef
+//# debugId=b1580db0-6822-5a25-b000-03705726eaf6

package/dist/completion-tree.json

@@ -73,6 +73,25 @@
       "arguments": [],
       "subcommands": []
     },
+    {
+      "name": "init",
+      "summary": "Set up a project so coding agents can use Hardfin",
+      "runs": true,
+      "flags": [
+        {
+          "name": "dry-run",
+          "description": "Say what would be written, and write nothing"
+        },
+        {
+          "name": "json",
+          "description": "Print machine-readable output, which is the default when stdout is not a terminal"
+        }
+      ],
+      "arguments": [
+        {}
+      ],
+      "subcommands": []
+    },
     {
       "name": "asset",
       "summary": "Asset commands",
@@ -2553,6 +2572,24 @@
       ],
       "subcommands": []
     },
+    {
+      "name": "types",
+      "summary": "Print TypeScript types for the Hardfin API",
+      "runs": true,
+      "flags": [
+        {
+          "name": "output",
+          "description": "Where to write the declarations, instead of standard output",
+          "valueName": "path"
+        },
+        {
+          "name": "json",
+          "description": "Print machine-readable output, which is the default when stdout is not a terminal"
+        }
+      ],
+      "arguments": [],
+      "subcommands": []
+    },
     {
       "name": "config",
       "summary": "Print what this invocation talks to, and where each value came from",

package/dist/{program-BdRDIa3u.js → program-CjKwnPeY.js}

@@ -1,20 +1,20 @@
 #!/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]="6057a656-73c2-55b1-9f09-873e3b83b368")}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]="5a591d32-0d31-5357-b447-e33420753351")}catch(e){}}();
 import { a as defineCommand, i as GLOBAL_FLAGS, r as ExitCode, t as toInvocation } from "./scrub-BN3gyBpR.js";
 import { n as toCompletion, t as toAnswer$1 } from "./completion-tree-rR_Rmeij.js";
 import { createRequire } from "node:module";
 import { Command, CommanderError, Option } from "commander";
 import { z } from "zod";
-import { accessSync, chmodSync, closeSync, constants, existsSync, mkdirSync, openAsBlob, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
-import { basename, delimiter, dirname, join, resolve } from "node:path";
+import { accessSync, chmodSync, closeSync, constants, existsSync, mkdirSync, openAsBlob, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { basename, delimiter, dirname, join, relative, resolve } from "node:path";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { arch, cpus, homedir, release, totalmem, type, version } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
 import { createServer } from "node:http";
 import { createInterface as createInterface$1 } from "node:readline";
-import { fileURLToPath } from "node:url";
 //#region src/report/expected.ts
 /**
 * ExpectedFailure is a failure the CLI anticipated: the person's input, their network, their
@@ -1486,7 +1486,7 @@ const uninstallCommand = defineCommand({
 * directory by itself, and every other shell is told to load the script from its startup
 * file, because not every bash has bash-completion to load it lazily.
 */
-function toPlan(shell, place) {
+function toPlan$1(shell, place) {
 	const content = `${toScript(shell)}\n`;
 	if (shell === "fish") {
 		const config = place.env["XDG_CONFIG_HOME"] || join(place.home, ".config");
@@ -1569,7 +1569,7 @@ function toShell(place) {
 }
 /** isInstalled answers whether install has written a script for any shell. */
 function isInstalled(place = toPlace()) {
-	return SHELLS.some((shell) => existsSync(toPlan(shell, {
+	return SHELLS.some((shell) => existsSync(toPlan$1(shell, {
 		...place,
 		toProfile: () => void 0
 	}).script.path));
@@ -1602,7 +1602,7 @@ async function runChange(input, change) {
 		writeFailure("invalid_arguments", `name the shell to ${change} for: ${SHELLS.join(", ")}`, input.isJSON);
 		return ExitCode.USAGE;
 	}
-	const plan = toPlan(shell, place);
+	const plan = toPlan$1(shell, place);
 	if (change === "install" && shell === "powershell" && !plan.startup) {
 		writeFailure("shell_unavailable", "PowerShell did not report its profile, so there is nowhere to load the script from", input.isJSON);
 		return ExitCode.ERROR;
@@ -1841,6 +1841,208 @@ const crashCommand = defineCommand({
 	run: () => Promise.reject(/* @__PURE__ */ new TypeError("hardfin __crash failed on purpose, to check that defects are reported"))
 });
 //#endregion
+//#region src/command/init.ts
+/** The markers around the section init owns in AGENTS.md, so a second run replaces only that. */
+const SECTION_START = "<!-- hardfin:start -->";
+const SECTION_END = "<!-- hardfin:end -->";
+/** Where agents look for skills: Codex and most others, then Claude Code. */
+const SKILL_DIRECTORIES = [".agents/skills", ".claude/skills"];
+const initCommand = defineCommand({
+	name: "init",
+	summary: "Set up a project so coding agents can use Hardfin",
+	description: "Writes the hardfin-cli skill, a Hardfin section in AGENTS.md, and the Hardfin MCP server for Claude Code, Cursor and VS Code. Running it again updates what it wrote and leaves everything else alone.",
+	arguments: [{
+		name: "directory",
+		description: "The project to set up, which is the working directory when omitted",
+		required: false
+	}],
+	flags: [{
+		name: "dry-run",
+		description: "Say what would be written, and write nothing",
+		schema: z.boolean()
+	}, {
+		name: "json",
+		description: "Print machine-readable output, which is the default when stdout is not a terminal",
+		schema: z.boolean()
+	}],
+	examples: [{
+		description: "Set up the project you are in",
+		command: "hardfin init"
+	}, {
+		description: "See what it would write first",
+		command: "hardfin init --dry-run"
+	}],
+	run: runInit
+});
+async function runInit(input) {
+	const target = resolve(input.args[0] ?? ".");
+	if (!existsSync(target) || !statSync(target).isDirectory()) {
+		writeFailure("invalid_arguments", `${target} is not a folder, so there is nothing to set up`, input.isJSON);
+		return ExitCode.USAGE;
+	}
+	const mcpUrl = `${input.resolved.settings.issuerUrl.replace(/\/+$/, "")}/mcp`;
+	const planned = toPlan(target, toPackageDirectory(), mcpUrl);
+	const isDryRun = input.flags["dryRun"] === true;
+	if (!isDryRun) for (const entry of planned) entry.write?.();
+	const changes = planned.map((entry) => entry.change);
+	if (input.isJSON) {
+		writeData({
+			directory: target,
+			dryRun: isDryRun,
+			mcpUrl,
+			changes
+		});
+		return ExitCode.OK;
+	}
+	const lines = changes.map((change) => `${change.action.padEnd(10)} ${change.path}${change.reason ? `  (${change.reason})` : ""}`);
+	const closing = isDryRun ? "Nothing was written, because this was a dry run." : "Start an agent here and ask it to use Hardfin.";
+	writeData([
+		...lines,
+		"",
+		closing
+	].join("\n"));
+	return ExitCode.OK;
+}
+/** toPlan works out every file init writes, without writing any of them. */
+function toPlan(target, packageDirectory, mcpUrl) {
+	const planned = [];
+	const skills = join(packageDirectory, "skills");
+	for (const skill of readdirSync(skills)) for (const file of toFiles(join(skills, skill))) {
+		const content = readFileSync(file, "utf8");
+		for (const place of SKILL_DIRECTORIES) planned.push(toFilePlan(target, join(place, skill, relative(join(skills, skill), file)), content));
+	}
+	const section = readFileSync(join(packageDirectory, "templates", "AGENTS.md"), "utf8").replaceAll("{{MCP_URL}}", mcpUrl);
+	planned.push(toFilePlan(target, "AGENTS.md", toAgentsFile(join(target, "AGENTS.md"), section)));
+	planned.push(toJSONPlan(target, ".mcp.json", (config) => toWithServer(config, "mcpServers", {
+		type: "http",
+		url: mcpUrl
+	})), toJSONPlan(target, ".cursor/mcp.json", (config) => toWithServer(config, "mcpServers", { url: mcpUrl })), toJSONPlan(target, ".vscode/mcp.json", (config) => toWithServer(config, "servers", {
+		type: "http",
+		url: mcpUrl
+	})));
+	return planned;
+}
+/** toAgentsFile puts the Hardfin section into AGENTS.md, replacing the one an earlier run wrote. */
+function toAgentsFile(path, section) {
+	const block = `${SECTION_START}\n${section.trimEnd()}\n${SECTION_END}\n`;
+	if (!existsSync(path)) return `# Agent instructions\n\n${block}`;
+	const current = readFileSync(path, "utf8");
+	const start = current.indexOf(SECTION_START);
+	const end = current.indexOf(SECTION_END);
+	if (start >= 0 && end > start) return `${current.slice(0, start)}${block}${current.slice(end + 20).replace(/^\n/, "")}`;
+	return `${current.trimEnd()}\n\n${block}`;
+}
+/** toWithServer adds the hardfin server to an MCP config, leaving every other server as it was. */
+function toWithServer(config, key, server) {
+	const servers = typeof config[key] === "object" && config[key] !== null ? config[key] : {};
+	return {
+		...config,
+		[key]: {
+			...servers,
+			hardfin: server
+		}
+	};
+}
+/** toFilePlan compares what a file holds with what init would write there. */
+function toFilePlan(target, path, content) {
+	const full = join(target, path);
+	const current = existsSync(full) ? readFileSync(full, "utf8") : void 0;
+	if (current === content) return { change: {
+		path,
+		action: "unchanged"
+	} };
+	return {
+		change: {
+			path,
+			action: current === void 0 ? "created" : "updated"
+		},
+		write: () => {
+			mkdirSync(dirname(full), { recursive: true });
+			writeFileSync(full, content);
+		}
+	};
+}
+/** toJSONPlan changes a JSON config, and leaves alone one it cannot read rather than overwrite it. */
+function toJSONPlan(target, path, change) {
+	const full = join(target, path);
+	let config = {};
+	if (existsSync(full)) try {
+		const parsed = JSON.parse(readFileSync(full, "utf8"));
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return { change: {
+			path,
+			action: "skipped",
+			reason: "it does not hold a JSON object, so it was left alone"
+		} };
+		config = parsed;
+	} catch {
+		return { change: {
+			path,
+			action: "skipped",
+			reason: "it does not hold JSON, so it was left alone"
+		} };
+	}
+	return toFilePlan(target, path, `${JSON.stringify(change(config), null, 2)}\n`);
+}
+/** toFiles lists every file under a folder. */
+function toFiles(directory) {
+	return readdirSync(directory).flatMap((name) => {
+		const path = join(directory, name);
+		return statSync(path).isDirectory() ? toFiles(path) : [path];
+	});
+}
+/** toPackageDirectory finds this package's own folder, which holds the skills and templates it ships. */
+function toPackageDirectory(from = dirname(fileURLToPath(import.meta.url))) {
+	for (let directory = from;; directory = dirname(directory)) {
+		const manifest = join(directory, "package.json");
+		if (existsSync(manifest) && JSON.parse(readFileSync(manifest, "utf8")).name === "@hardfin/cli") return directory;
+		if (dirname(directory) === directory) throw new Error("the @hardfin/cli package folder could not be found, so its skills cannot be copied");
+	}
+}
+//#endregion
+//#region src/command/types.generated.ts
+/** API_TYPES is the TypeScript hardfin types prints. */
+const API_TYPES = "// Types for the Hardfin API, version 2026-09-17, generated from its published document.\n// Regenerate them with hardfin types after upgrading the CLI.\n\n/** ApiError is one entry in a response's errors. */\nexport interface ApiError {\n    error: string;\n    statusCode: number;\n}\n\n/** ApiEnvelope is the shape every response takes, with the record or records in data. */\nexport interface ApiEnvelope<T> {\n    data: T;\n    metadata: {\n        errors?: ApiError[] | null;\n        requestId?: string;\n        requestTime?: string;\n        statusCode?: number;\n        pagination?: unknown;\n    };\n}\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type ArchivedState = \"all\" | \"false\" | \"true\";\n\nexport type Asset = SparseAsset & AssetLocationData & {\n    /** The asset's cost basis, depreciation, and accounting history. */\n    accounting?: AssetAccountingDetails;\n    /** The asset's recent events, such as shipments and deliveries. */\n    activity?: AssetEvent[];\n    /** A free-form description of the asset. */\n    description?: string | null;\n    /** The number of files attached to the asset. */\n    fileCount?: number;\n    /** The day the asset entered inventory. */\n    inInventoryDate?: string;\n    /** The asset's value for each custom field its item defines. */\n    metadata?: AssetMetadataFieldWrapper[];\n    /** Who owns the asset now. */\n    ownership?: AssetOwnership;\n    /** The project the asset is assigned to, or null when it is unassigned. */\n    project?: SparseProject | null;\n    /** How and when the asset was scrapped, or null when it has not been. */\n    scrappedContext?: AssetScrappedContext | null;\n    /** The number of tickets about the asset. */\n    ticketCount?: number;\n    /** The number of links attached to the asset. */\n    urlLinkCount?: number;\n};\n\nexport interface AssetAccountingDetails {\n    /** The asset's inventory cost basis, before deployment costs, which is what inventory is relieved by when the asset leaves it. */\n    acquisitionCogs?: string | null;\n    /** The asset's share of overhead. */\n    allocatedIndirect?: string | null;\n    /** The problems that keep the asset's accounting from being computed, such as a missing cost basis. */\n    assetExceptions?: AssetExceptionType[];\n    /** The parts cost. */\n    billOfMaterials?: string | null;\n    /** The cost basis on the books now, the acquisition basis in inventory and the deployed basis once the asset is a fixed asset. */\n    capitalizedCosts?: string | null;\n    /** The capitalizations and impairments made to the asset's cost after it was acquired. */\n    costAdjustments?: AssetCostAdjustment[];\n    /** The method the asset is depreciated by. */\n    depreciationModel?: Depreciation;\n    /** The asset's book value month by month, from its inventory month, or null while it has an accounting exception. */\n    depreciationPeriods?: AssetDepreciationChartPeriod[] | null;\n    /** The labor cost to build the asset. */\n    directLabor?: string | null;\n    /** The shipping cost to receive the asset. */\n    freightInbound?: string | null;\n    /** The shipping cost to deploy the asset, a deployment cost. */\n    freightOutbound?: string | null;\n    /** The day the asset was put into service and began depreciating. */\n    inServiceDate?: string | null;\n    /** The cost to install the asset, a deployment cost. */\n    installation?: string | null;\n    /** The financing cost of the asset. */\n    interest?: string | null;\n    /** Whether Hardfin sets the in-service date itself rather than keeping one a person entered. */\n    isInServiceDateManagedAutomatically?: boolean;\n    /** The value the asset keeps at the end of its useful life. */\n    salvageValue?: string | null;\n    /** A single cost entered in place of the cost components. */\n    simpleCostBasis?: string | null;\n    /** The import duty paid on the asset. */\n    tariffs?: string | null;\n    /** The tax paid on the asset. */\n    tax?: string | null;\n    /** The deployed cost basis, including deployment costs, which is what is capitalized once the asset is put into service. */\n    totalPotentialCOGS?: string | null;\n    /** The number of months the asset is depreciated over. */\n    usefulLife?: number | null;\n    /** The changes made to the asset's useful life. */\n    usefulLifeRevisions?: AssetUsefulLifeRevision[];\n}\n\nexport interface AssetCostAdjustment {\n    /** CAPITALIZATION to add to the cost basis, or IMPAIRMENT to write it down. */\n    adjustmentType?: CostAdjustmentType;\n    /** The size of the adjustment. */\n    amount?: string;\n    /** When the adjustment was recorded. */\n    createdAt?: string;\n    /** The person who recorded the adjustment. */\n    createdBy?: SparsePerson;\n    /** The day the adjustment takes effect. */\n    effectiveDate?: string;\n    /** The cost adjustment's key. */\n    key?: string;\n    /** Free-form detail about the adjustment. */\n    notes?: string | null;\n    /** Why the cost changed. */\n    reason?: CostAdjustmentReason;\n}\n\nexport interface AssetDepreciationChartPeriod {\n    /** The depreciation charged from the in-service date through the end of the period. */\n    accumulated?: string;\n    /** The asset's value on the books at the end of the period. */\n    bookValue?: string;\n    /** The last day of the month the period covers. */\n    date?: string;\n    /** The depreciation charged in the period. */\n    depreciation?: string;\n}\n\nexport interface AssetEvent {\n    /** When the event was recorded. */\n    createdAt?: string;\n    /** The IANA time zone the event's times were entered in. */\n    eventTimezone?: string;\n    /** When the event is expected to happen, or null when no one has said. */\n    expectedAt?: string | null;\n    /** The event's unique identifier. */\n    id?: string;\n    /** Whether the event has to happen for its group to complete. */\n    isRequired?: boolean;\n    /** When the event happened, or null while it has not. */\n    occurredAt?: string | null;\n    /** The day the event was promised to a customer, or null when none was. */\n    promiseDate?: string | null;\n    /** The event's values a person set, such as carrier tracking. */\n    properties?: AssetEventProperty[];\n    /** The event's position within its group. */\n    sequence?: number;\n    /** When someone marked the event as happened in Hardfin, or null while it has not happened. */\n    triggeredAt?: string | null;\n    /** What kind of event this is. */\n    type?: AssetEventType;\n}\n\nexport interface AssetEventConfiguration {\n    /** The properties an event of the type carries. */\n    properties?: AssetEventProperty[];\n    /** The kind of event the configuration describes. */\n    type?: AssetEventType;\n}\n\nexport interface AssetEventGroup {\n    /** The kind of group this is, and the events it carries. */\n    configuration?: AssetEventGroupConfiguration;\n    /** Where the movement ends, or null when the group does not move the asset. */\n    destination?: SparseLocationWithParent | null;\n    /** The events the group has recorded so far. */\n    events?: AssetEvent[];\n    /** The event group's unique identifier. */\n    id?: string;\n    /** The event group's key, which the event group endpoints take as eventGroupKey. */\n    key?: string;\n    /** Where the movement started, or null when the group does not move the asset. */\n    origin?: SparseLocationWithParent | null;\n    /** The shipment the movement travels on, or null when it travels on none. */\n    shipment?: SparseShipment | null;\n}\n\nexport interface AssetEventGroupConfiguration {\n    /** The events a group of the kind carries, in the order they happen. */\n    events?: AssetEventConfiguration[];\n    /** The configuration's unique identifier. */\n    id?: string;\n    /** The configuration's key. */\n    key?: string;\n    /** What the configuration is called, such as ship and deliver. */\n    name?: string;\n}\n\nexport interface AssetEventProperty {\n    /** The event property's unique identifier. */\n    id?: string;\n    /** Whether Hardfin sets the property itself rather than a person, which responses leave out. */\n    isSystemProperty?: boolean;\n    /** The property's display name. */\n    label?: string;\n    /** The kind of value the property holds, such as CARRIER_TRACKING or CACHED_LOCATION. */\n    type?: string;\n    /** The property's value, whose JSON shape depends on the property's type. */\n    value?: unknown[] | boolean | number | Record<string, unknown> | string | null;\n}\n\nexport interface AssetEventType {\n    /** The event type's unique identifier. */\n    id?: string;\n    /** The event type's name, such as Ship or Deliver. */\n    name?: string;\n    /** Whether an event of this type only happens as part of a group, such as a shipment. */\n    requiresEventGroup?: boolean;\n}\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type AssetExceptionType = \"DEPLOYMENT_WITHOUT_ACQUISITION\" | \"DISPOSAL_DATE_BEFORE_INVENTORY\" | \"FIRST_ASSIGNMENT_BEFORE_INVENTORY\" | \"FIRST_MOVEMENT_BEFORE_INVENTORY\" | \"FIRST_SALE_DATE_BEFORE_INVENTORY\" | \"IN_SERVICE_DATE_BEFORE_INVENTORY\" | \"MISSING_COST_BASIS\" | \"MISSING_USEFUL_LIFE\" | \"SALVAGE_EXCEEDS_50_PERCENT\" | \"UNKNOWN\";\n\nexport interface AssetFile {\n    /** The file's unique identifier. */\n    id?: string;\n    /** Whether the file is readable with any organization's API key. */\n    isPublic?: boolean;\n    /** The file's key, which the file endpoints take as fileKey. */\n    key?: string;\n    /** The file's media type, or an empty string when the upload named none. */\n    mimeType?: string;\n    /** The name the file had when it was uploaded. */\n    name?: string;\n    /** The file's size in bytes. */\n    size?: number;\n    /** The file type the file was uploaded as. */\n    type?: string;\n    /** When the file was uploaded. */\n    uploadedAt?: string;\n}\n\n/** Whether an asset works, is broken, awaits review, or has been scrapped. Accepted in any case. The listed spelling is the one the API sends back. */\nexport type AssetFunctionalStatus = \"FUNCTIONAL\" | \"NEEDS_REVIEW\" | \"NON-FUNCTIONAL\" | \"SCRAPPED\";\n\nexport interface AssetFunctionalStatusHistoryItem {\n    /** When the asset left the status, or null while it still holds it. */\n    end?: string | null;\n    /** When the asset took the status. */\n    start?: string;\n    /** Whether the asset worked, was broken, awaited review, or had been scrapped through the period. */\n    status?: AssetFunctionalStatus;\n}\n\nexport interface AssetListing {\n    /** The page of records. */\n    results?: Asset[];\n    /** The number of records that match the filters, across every page. */\n    totalCount?: number;\n}\n\nexport interface AssetLocationData {\n    /** Where the asset is, or null while it is in transit. */\n    currentLocation?: SparseLocationWithParent | null;\n    /** Whether the asset has shipped and not yet been delivered. */\n    inTransit?: boolean;\n    /** Where a planned or in-progress move takes the asset, or null when none is planned. */\n    nextLocation?: SparseLocationWithParent | null;\n    /** The location the asset was at before its current one, or null when it has not moved. */\n    previousLocation?: SparseLocationWithParent | null;\n}\n\nexport interface AssetMetadataField {\n    /** The item field's unique identifier. */\n    id?: string;\n    /** The item field's key. */\n    key?: string;\n    /** The field's display name. */\n    label?: string;\n    /** The field's position within its section, starting at 0. */\n    order?: number;\n    /** The group the field is shown in, starting at 0. */\n    section?: number;\n    /** The kind of value the field holds, which decides the JSON type of its value. */\n    type?: ItemFieldType;\n}\n\nexport type AssetMetadataFieldWrapper = {\n    field?: {\n        type?: \"BOOLEAN\";\n    };\n    value?: boolean | null;\n} | {\n    field?: {\n        type?: \"DATE\";\n    };\n    value?: string | null;\n} | {\n    field?: {\n        type?: \"DATE_TIME\";\n    };\n    value?: string | null;\n} | {\n    field?: {\n        type?: \"INTEGER\";\n    };\n    value?: number | null;\n} | {\n    field?: {\n        type?: \"MULTILINE_TEXT\";\n    };\n    value?: string | null;\n} | {\n    field?: {\n        type?: \"NUMBER\";\n    };\n    value?: number | null;\n} | {\n    field?: {\n        type?: \"TEXT\";\n    };\n    value?: string | null;\n} | {\n    field?: {\n        type?: \"TIME\";\n    };\n    value?: string | null;\n};\n\nexport interface AssetMoveToPlan {\n    /** The ID of the asset to move. */\n    assetId?: string;\n    /** When the asset reaches its destination, or null when the move only ships. */\n    deliverAt?: string | null;\n    /** The client's own name for the move, which the plan echoes back beside its answer. */\n    id?: string;\n    /** When the asset leaves its origin, or null when the move only delivers. */\n    shipAt?: string | null;\n}\n\nexport interface AssetOwnership {\n    /** The customer that owns the asset, or null when your organization owns it. */\n    customer?: SparseCustomer | null;\n    /** The day the asset's current owner took ownership, or null when its ownership has never changed. */\n    ownershipChangeDate?: string | null;\n}\n\nexport interface AssetOwnershipHistoryItem {\n    /** When the segment was recorded. */\n    createdAt?: string;\n    /** The customer that owned the asset during the segment, or null when your organization did. */\n    customer?: SparseCustomer | null;\n    /** The day the segment's owner took ownership. */\n    date?: string;\n    /** The ownership segment's unique identifier. */\n    id?: string;\n    /** The ownership segment's key, which the segment endpoints take as segmentKey. */\n    key?: string;\n    /** When the segment was last changed. */\n    lastModifiedAt?: string;\n    /** What the owner paid for the asset, or null when no price was recorded. */\n    salePrice?: string | null;\n}\n\nexport interface AssetPlannedIntersection {\n    /** The ID of the event group the move would collide with, or null when none names one. */\n    aegId?: string | null;\n    /** The key of the event group the move would collide with, or null when none names one. */\n    aegKey?: string | null;\n    /** When the colliding movement ends, or null while it has no end. */\n    end?: string | null;\n    /** When the colliding movement starts. */\n    start?: string;\n}\n\nexport interface AssetPlannedMove {\n    /** The client's own name for the move, echoed from the plan it asked about. */\n    id?: string;\n    /** The movement the move would collide with, or null when it collides with none. */\n    intersection?: AssetPlannedIntersection | null;\n    /** Whether the move can be carried out as asked. */\n    isValid?: boolean;\n}\n\nexport interface AssetProposedMultiMove {\n    /** The ID of the asset to move. */\n    assetId?: string;\n    /** When the asset reaches its destination, which a move sends unless it ships. */\n    deliverAt?: string | null;\n    /** The timezone the delivery time was entered in, or null for the organization's. */\n    deliverAtTimezone?: string | null;\n    /** The ID of the location the asset arrives at. */\n    destinationId?: string;\n    /** The ID of the location the asset leaves. */\n    originId?: string;\n    /** When the asset leaves its origin, which a move sends unless it delivers. */\n    shipAt?: string | null;\n    /** The timezone the ship time was entered in, or null for the organization's. */\n    shipAtTimezone?: string | null;\n}\n\nexport interface AssetScrappedContext {\n    /** The day the asset was scrapped. */\n    disposalDate?: string;\n    /** What the scrapped asset was sold for, or null when it was not sold. */\n    disposalPrice?: string | null;\n    /** Why the asset was scrapped. */\n    disposalReason?: string | null;\n}\n\nexport interface AssetUpdateMetadataItem {\n    /** The ID of the item field to set on the asset. */\n    fieldId?: string;\n    /** The field's new value, in the JSON type the field's type calls for, or null to clear it. */\n    value?: unknown[] | boolean | number | Record<string, unknown> | string | null;\n}\n\nexport interface AssetUsefulLifeRevision {\n    /** When the revision was recorded. */\n    createdAt?: string;\n    /** The person who recorded the revision. */\n    createdBy?: SparsePerson;\n    /** The day the new useful life takes effect. */\n    effectiveDate?: string;\n    /** The revision's key. */\n    key?: string;\n    /** Free-form detail about the revision. */\n    notes?: string | null;\n    /** Why the useful life changed. */\n    reason?: UsefulLifeRevisionReason;\n    /** The asset's new useful life in months. */\n    usefulLifeMonths?: number;\n}\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type BillingFrequency = \"ANNUALLY\" | \"BIENNIALLY\" | \"BIWEEKLY\" | \"DAILY\" | \"MONTHLY\" | \"ONCE\" | \"QUADRENNIALLY\" | \"QUARTERLY\" | \"QUINQUENNIALLY\" | \"SEMIANNUALLY\" | \"TRIENNIALLY\" | \"WEEKLY\";\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type BillingSchedule = \"MILESTONE\" | \"PERIODIC\";\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type BillingTiming = \"ADVANCE\" | \"ARREARS\";\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type CostAdjustmentReason = \"ADDITION\" | \"BETTERMENT\" | \"DAMAGE\" | \"INSTALLATION\" | \"LIFE_EXTENSION\" | \"MARKET_DECLINE\" | \"OBSOLESCENCE\" | \"OTHER\" | \"REGULATORY\";\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type CostAdjustmentType = \"CAPITALIZATION\" | \"IMPAIRMENT\";\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type CostBasisMode = \"ADVANCED\" | \"SIMPLE\" | null;\n\n/** The kind of credential a request was made with. Accepted in any case. The listed spelling is the one the API sends back. | Value | Description | | --- | --- | | `API_KEY` | An API key, for an integration that runs unattended | | `OAUTH` | An OAuth access token, issued to an application a person connected | | `SESSION` | A person signed in to Hardfin in a browser | */\nexport type CredentialType = \"API_KEY\" | \"OAUTH\" | \"SESSION\";\n\nexport interface Currency {\n    /** The value as a decimal string with two decimal places. */\n    amount?: string;\n    /** The value's ISO 4217 currency code. */\n    isoCode?: string;\n}\n\nexport type Customer = SparseCustomer & {\n    /** The number of the customer's active projects. */\n    activeProjectCt?: number;\n    /** The number of assets the customer owns. */\n    assetCount?: number;\n    /** The number of assets at the customer's locations. */\n    assetsAtLocation?: number;\n    /** The address invoices are sent to. */\n    billingAddress?: string | null;\n    /** The person who receives the customer's invoices. */\n    billingContact?: CustomerBillingContact | null;\n    /** A free-form note about the customer. */\n    comment?: string | null;\n    /** The customer's web domain, used to look up its logo. */\n    domain?: string | null;\n    /** The customer's identifier in another system. */\n    externalId?: string | null;\n    /** The number of the customer's incomplete projects. */\n    incompleteProjectCt?: number;\n    /** The customer's links to integrated systems. */\n    integrations?: SharedIntegration[];\n    /** The number of the customer's locations. */\n    locationCount?: number;\n    /** The customer's locations. */\n    locations?: SparseLocationWithParent[];\n    /** The storage key of the customer's logo file. */\n    logoFileKey?: string | null;\n    /** The number of the customer's past projects. */\n    pastProjectCt?: number;\n    /** The number of the customer's upcoming projects. */\n    upcomingProjectCt?: number;\n};\n\nexport interface CustomerBillingContact {\n    /** The billing contact's email address. */\n    email?: string | null;\n    /** The billing contact's name. */\n    name?: string | null;\n    /** The billing contact's phone number. */\n    phone?: string | null;\n}\n\nexport interface CustomerListing {\n    /** The page of records. */\n    results?: Customer[];\n    /** The number of records that match the filters, across every page. */\n    totalCount?: number;\n}\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type Depreciation = \"DOUBLE_DECLINING\" | \"STRAIGHT_LINE\" | \"SUM_YEAR\" | \"UNIT_OF_PRODUCTION\" | null;\n\nexport interface Error {\n    error: string;\n    statusCode: number;\n}\n\nexport interface FileNewUpload {\n    /** The uploaded file's unique identifier. */\n    fileId?: string;\n    /** The uploaded file's key, which the file endpoints take as fileKey. */\n    fileKey?: string;\n}\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type FrontendItemType = \"BULK\" | \"DEVICE\" | \"SERVICE\";\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type IntegrationCategory = \"CRM\" | \"ERP\";\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type IntegrationID = \"HUBSPOT\" | \"NETSUITE\" | \"NONE\" | \"QBO\" | \"SFDC\";\n\nexport interface Item {\n    /** Whether a BULK item records serial numbers on its units, which is false for SERVICE and DEVICE items. */\n    acceptsBulkSerials?: boolean;\n    /** The number of assets of a DEVICE item, and null for other types. */\n    assetCount?: number | null;\n    /** A free-form description of the item. */\n    description?: string | null;\n    /** The item's unique identifier. */\n    id?: string;\n    /** The item's links to integrated systems. */\n    integrations?: SharedIntegration[];\n    /** Whether the item is archived. */\n    isArchived?: boolean;\n    /** The item's key, which the item endpoints take as itemKey. */\n    key?: string;\n    /** When the item was last changed. */\n    lastUpdatedAt?: string | null;\n    /** The person who last changed the item. */\n    lastUpdatedBy?: SparsePerson;\n    /** The item's display name. */\n    name?: string;\n    /** Whether the item's units carry serial numbers, which is true for a DEVICE item and for a BULK item that accepts serials. */\n    shouldRenderSerialFields?: boolean;\n    /** The item's stock keeping unit, unique within your organization. */\n    sku?: string;\n    /** SERVICE for a non-physical item, DEVICE for a physical item tracked by serial number, or BULK for a part tracked by quantity. */\n    type?: FrontendItemType;\n}\n\nexport interface ItemAccounting {\n    /** The default share of overhead for one unit. */\n    allocatedIndirect?: string | null;\n    /** The default parts cost for one unit. */\n    billOfMaterials?: string | null;\n    /** The default method one unit is depreciated by. */\n    depreciationModel?: Depreciation;\n    /** The default labor cost to build one unit. */\n    directLabor?: string | null;\n    /** The default shipping cost to receive one unit. */\n    freightInbound?: string | null;\n    /** The default shipping cost to deliver one unit. */\n    freightOutbound?: string | null;\n    /** The default cost to install one unit. */\n    installation?: string | null;\n    /** The default financing cost for one unit. */\n    interest?: string | null;\n    /** The default value one unit keeps at the end of its useful life. */\n    salvageValue?: string | null;\n    /** A single default cost for one unit, used instead of the cost components. */\n    simpleCostBasis?: string | null;\n    /** The default import duty paid on one unit. */\n    tariffs?: string | null;\n    /** The default tax paid on one unit. */\n    tax?: string | null;\n    /** The default cost of goods sold for one unit, which is the simple cost basis when set and otherwise the sum of the cost components. */\n    totalCOGS?: string | null;\n    /** The default number of months one unit is depreciated over. */\n    usefulLife?: number | null;\n}\n\nexport interface ItemBOMItem {\n    /** The BULK part the bill of materials uses. */\n    item?: SparseItem;\n    /** The number of the part one unit of the item uses. */\n    quantity?: number;\n}\n\nexport interface ItemDetail {\n    /** Whether a BULK item records serial numbers on its units, which is false for SERVICE and DEVICE items. */\n    acceptsBulkSerials?: boolean;\n    /** The default costs and depreciation for a unit of a DEVICE or BULK item. */\n    accounting?: ItemAccounting;\n    /** The number of assets of a DEVICE item, and null for other types. */\n    assetCount?: number | null;\n    /** The bill of materials, the BULK parts one unit of the item is built from, or null when it has none. */\n    bom?: ItemBOMItem[] | null;\n    /** The pricing a project line item's billing plan starts from when it sells the item, or null when the item has none. */\n    defaultPricing?: ItemPricing | null;\n    /** A free-form description of the item. */\n    description?: string | null;\n    /** The custom fields each asset of a DEVICE item can hold. */\n    fields?: ItemField[];\n    /** Whether each unit of the item is tracked as its own asset, which is true for a DEVICE item. */\n    hasAssets?: boolean;\n    /** The item's unique identifier. */\n    id?: string;\n    /** The item's links to integrated systems. */\n    integrations?: SharedIntegration[];\n    /** The number of inventory movements of a BULK item, and null for other types. */\n    inventoryMovementCount?: number | null;\n    /** Whether the item is archived. */\n    isArchived?: boolean;\n    /** Whether the item is physical, which is true for DEVICE and BULK items. */\n    isPhysical?: boolean;\n    /** The item's key, which the item endpoints take as itemKey. */\n    key?: string;\n    /** When the item was last changed. */\n    lastUpdatedAt?: string | null;\n    /** The person who last changed the item. */\n    lastUpdatedBy?: SparsePerson;\n    /** The item's display name. */\n    name?: string;\n    /** Whether the item's units carry serial numbers, which is true for a DEVICE item and for a BULK item that accepts serials. */\n    shouldRenderSerialFields?: boolean;\n    /** The item's stock keeping unit, unique within your organization. */\n    sku?: string;\n    /** SERVICE for a non-physical item, DEVICE for a physical item tracked by serial number, or BULK for a part tracked by quantity. */\n    type?: FrontendItemType;\n}\n\nexport interface ItemField {\n    /** The field's unique identifier. */\n    id?: string;\n    /** The field's key, which the item field endpoints take as fieldKey. */\n    key?: string;\n    /** The field's display name. */\n    label?: string;\n    /** The number of assets that hold a value for the field. */\n    metadataCount?: number;\n    /** The field's position within its section, starting at 0. */\n    order?: number;\n    /** The group the field is shown in, starting at 0. */\n    section?: number;\n    /** The kind of value the field holds. */\n    type?: ItemFieldType;\n}\n\nexport interface ItemFieldOrderingUpdateItem {\n    /** The ID of the item field to move. */\n    fieldId?: string;\n    /** The field's position within its section, starting at 0. */\n    order?: number;\n    /** The group the field is shown in, starting at 0. */\n    section?: number;\n}\n\n/** The kind of value an item's custom field holds. Accepted in any case. The listed spelling is the one the API sends back. */\nexport type ItemFieldType = \"BOOLEAN\" | \"DATE\" | \"DATE_TIME\" | \"INTEGER\" | \"MULTILINE_TEXT\" | \"NUMBER\" | \"TEXT\" | \"TIME\";\n\nexport interface ItemListing {\n    /** The page of records. */\n    results?: Item[];\n    /** The number of records that match the filters, across every page. */\n    totalCount?: number;\n}\n\nexport interface ItemPricing {\n    /** How often a PERIODIC charge recurs. */\n    chargeFrequency?: BillingFrequency | null;\n    /** PERIODIC to charge on a recurring cadence, or MILESTONE to charge when a milestone is reached. */\n    chargeSchedule?: BillingSchedule | null;\n    /** The default price for the whole line, used when pricingMode is FIXED. */\n    fixedPrice?: Currency | null;\n    /** How often the charges are invoiced. */\n    invoiceFrequency?: BillingFrequency | null;\n    /** ADVANCE to invoice a period before it starts, or ARREARS to invoice it after it ends. */\n    invoiceMode?: BillingTiming | null;\n    /** PER_UNIT to charge the unit price for each unit, or FIXED to charge the fixed price for the line whatever its quantity. */\n    pricingMode?: PricingMode | null;\n    /** The default price for each unit, used when pricingMode is PER_UNIT. */\n    unitPrice?: Currency | null;\n}\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type ItemType = \"marked_bulk\" | \"service\" | \"tracked_device\" | \"unmarked_bulk\";\n\nexport type Location = SparseLocationWithIntegration & {\n    /** The number of active projects at the location. */\n    activeProjectCount?: number;\n    /** The number of assets currently at the location. */\n    assetCount?: number;\n    /** The number of incomplete projects at the location. */\n    incompleteProjectCount?: number;\n    /** The number of past projects at the location. */\n    pastProjectCount?: number;\n    /** The number of upcoming projects at the location. */\n    upcomingProjectCount?: number;\n};\n\nexport interface LocationListing {\n    /** The page of records. */\n    results?: Location[];\n    /** The number of records that match the filters, across every page. */\n    totalCount?: number;\n}\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type LocationType = \"SITE\" | \"UNKNOWN\" | \"ZONE\" | null;\n\nexport interface Metadata {\n    errors: Error[] | null;\n    /** The identifier to quote when asking Hardfin about this request. */\n    requestId: string;\n    /** How long the server took to answer. */\n    requestTime: string;\n    statusCode: number;\n}\n\nexport interface MetadataLocationComponents {\n    /** The first line of the street address. */\n    addressLine1?: string | null;\n    /** The second line of the street address, such as a suite. */\n    addressLine2?: string | null;\n    /** The city. */\n    city?: string | null;\n    /** The country. */\n    country?: string | null;\n    /** The whole address on one line. */\n    formattedAddress?: string | null;\n    /** The postal or ZIP code. */\n    postalCode?: string | null;\n    /** The state or region. */\n    state?: string | null;\n}\n\nexport interface MetadataLocationSite {\n    /** The location's structured address, which a zone reads from its parent site. */\n    address?: MetadataLocationComponents | null;\n    /** Google's place ID for the address, when it was found through Google. */\n    googlePlaceId?: string | null;\n    /** The location's latitude, sent as a decimal string. */\n    latitude?: string | null;\n    /** The location's longitude, sent as a decimal string. */\n    longitude?: string | null;\n    /** The person or business that receives shipments at the location. */\n    shippingName?: string | null;\n}\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type PricingMode = \"FIXED\" | \"PER_UNIT\";\n\n/** The item type a request asks an item to become. Accepted in any case. The listed spelling is the one the API sends back. */\nexport type RequestedItemType = \"BULK\" | \"DEVICE\" | \"SERVICE\";\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type ScrappedState = \"all\" | \"false\" | \"true\";\n\nexport interface SharedBool {\n    /** Whether the operation completed. */\n    success?: boolean;\n}\n\nexport interface SharedIntegration {\n    /** The Hardfin error code of the failed sync, or null when the sync did not fail. */\n    errorCode?: number | null;\n    /** The integrated system, such as SFDC or HUBSPOT. */\n    id?: IntegrationID;\n    /** Whether the last sync with the external system failed. */\n    inError?: boolean;\n    /** Whether a sync with the external system is pending. */\n    isSyncing?: boolean;\n    /** The system's display name. */\n    label?: string;\n    /** A URL to the linked record in the external system. */\n    link?: string | null;\n    /** Whether the record differs from the external system and needs a person to review it. */\n    needsReview?: boolean;\n    /** The kind of system, CRM or ERP. */\n    type?: IntegrationCategory;\n}\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type SortOrder = \"ASC\" | \"DESC\";\n\nexport interface SparseAsset {\n    /** Whether the asset works, is broken, awaits review, or has been scrapped. */\n    functionalStatus?: AssetFunctionalStatus;\n    /** The asset's unique identifier. */\n    id?: string;\n    /** The day the asset entered inventory. */\n    inInventoryDate?: string;\n    /** Whether the asset is archived. */\n    isArchived?: boolean;\n    /** Whether the asset has shipped and not yet been delivered. */\n    isInTransit?: boolean;\n    /** The catalog item the asset is a unit of. */\n    item?: SparseItem;\n    /** The asset's key, which the asset endpoints take as assetKey. */\n    key?: string;\n    /** The asset's serial number, unique within its item. */\n    serial?: string;\n}\n\nexport interface SparseCustomer {\n    /** The customer's unique identifier. */\n    id?: string;\n    /** Whether the customer is archived. */\n    isArchived?: boolean;\n    /** Whether the company is a customer. */\n    isCustomer?: boolean;\n    /** Whether the company is a supplier. */\n    isSupplier?: boolean;\n    /** The customer's key, which the customer endpoints take as customerKey. */\n    key?: string;\n    /** The customer's display name. */\n    name?: string;\n}\n\nexport interface SparseItem {\n    /** Whether each unit of the item is tracked as its own asset, which is true for a DEVICE item. */\n    hasAssets?: boolean;\n    /** The item's unique identifier. */\n    id?: string;\n    /** Whether the item is archived. */\n    isArchived?: boolean;\n    /** Whether the item is physical, which is true for DEVICE and BULK items. */\n    isPhysical?: boolean;\n    /** The item's key, which the item endpoints take as itemKey. */\n    key?: string;\n    /** The item's display name. */\n    name?: string;\n    /** Whether the item's units carry serial numbers, which is true for a DEVICE item and for a BULK item that accepts serials. */\n    shouldRenderSerialFields?: boolean;\n    /** The item's stock keeping unit, unique within your organization. */\n    sku?: string;\n    /** SERVICE for a non-physical item, DEVICE for a physical item tracked by serial number, or BULK for a part tracked by quantity. */\n    type?: FrontendItemType;\n    /** The unit the item's quantities are counted in. */\n    unitOfMeasure?: UnitOfMeasure;\n}\n\nexport type SparseLocation = MetadataLocationSite & {\n    /** The number of archived zones at a site. */\n    archivedZoneCount?: number;\n    /** The customer a zone is designated for, such as for reservations, provisioning or a 3PL. */\n    consignee?: SparseCustomer | null;\n    /** The customer the location is assigned to, which a zone reads from its parent site, or null for your organization's own locations. */\n    customer?: SparseCustomer | null;\n    /** A free-form description of a zone. */\n    description?: string | null;\n    /** The location's unique identifier. */\n    id?: string;\n    /** Whether the location is archived. */\n    isArchived?: boolean;\n    /** Whether assets at the location count as inventory for reporting. */\n    isInventory?: boolean;\n    /** Whether a zone sets its own isInventory rather than inheriting its parent site's. */\n    isInventoryOverride?: boolean;\n    /** Whether a third-party logistics (3PL) provider fulfills orders from the location. */\n    isThirdPartyEnabled?: boolean;\n    /** Whether assets make only occasional or temporary stops at the location, which hides it from location lists by default. */\n    isTransient?: boolean;\n    /** The location's key, which the location endpoints take as locationKey. */\n    key?: string;\n    /** The location's display name. */\n    name?: string;\n    /** The 3PL provider's identifier for the location. */\n    thirdPartyIdentifier?: string | null;\n    /** SITE for a site, or ZONE for a zone within a site. */\n    type?: LocationType;\n    /** The number of zones at a site. */\n    zoneCount?: number;\n    /** The site's zones. */\n    zones?: SparseZone[];\n};\n\nexport type SparseLocationWithIntegration = SparseLocationWithParent & {\n    /** The location's links to integrated systems. */\n    integrations?: SharedIntegration[];\n};\n\nexport type SparseLocationWithParent = SparseLocation & {\n    /** The site a zone belongs to, or null for a site. */\n    parentLocation?: SparseLocation | null;\n};\n\nexport interface SparseOrganization {\n    /** The organization's ID */\n    id?: string;\n    /** The public identifier that can be used in URLs */\n    key?: string;\n    /** The name of the organization */\n    name?: string;\n}\n\nexport interface SparsePerson {\n    /** The person's first name. */\n    firstName?: string | null;\n    /** The person's unique identifier. */\n    id?: string;\n    /** The person's key. */\n    key?: string;\n    /** The person's last name. */\n    lastName?: string | null;\n}\n\nexport interface SparseProject {\n    /** The customer the project is for. */\n    customer?: SparseCustomer | null;\n    /** The day the project ends. */\n    end?: string | null;\n    /** The project's unique identifier. */\n    id?: string;\n    /** The project's links to integrated systems. */\n    integrations?: SharedIntegration[];\n    /** Whether the project is archived. */\n    isArchived?: boolean;\n    /** The project's key. */\n    key?: string;\n    /** The project's display name. */\n    name?: string;\n    /** The name of the project's payment term. */\n    paymentTermLabel?: string | null;\n    /** The customer's purchase order number, which new invoices for the project carry. */\n    purchaseOrderNumber?: string | null;\n    /** The day the project starts. */\n    start?: string | null;\n    /** Whether the project is upcoming, active, or past, judged from its dates. */\n    status?: string;\n}\n\nexport interface SparseShipment {\n    /** When the shipment arrived, or null while it has not. */\n    deliveredAt?: string | null;\n    /** The shipment's unique identifier. */\n    id?: string;\n    /** The shipment's key. */\n    key?: string;\n    /** The number the shipment is known by. */\n    shipmentNumber?: string;\n    /** What kind of movement the shipment carries. */\n    shipmentType?: string;\n    /** When the shipment left, or null while it has not. */\n    shippedAt?: string | null;\n}\n\nexport interface SparseZone {\n    /** The number of assets in the zone. */\n    assetCount?: number;\n    /** The customer the zone is designated for, such as for reservations, provisioning or a 3PL. */\n    consignee?: SparseCustomer | null;\n    /** A free-form description of the zone. */\n    description?: string | null;\n    /** The zone's unique identifier. */\n    id?: string;\n    /** Whether the zone is archived. */\n    isArchived?: boolean;\n    /** Whether assets in the zone count as inventory for reporting. */\n    isInventory?: boolean;\n    /** The zone's key. */\n    key?: string;\n    /** The zone's display name, unique within its site. */\n    name?: string;\n}\n\nexport interface Token {\n    /** When the API key was created, the application was connected, or the person signed in. */\n    createdAt?: string;\n    /** When the access token or session expires, or null for an API key, which does not. */\n    expiresAt?: string | null;\n    /** The API key's public identifier or the application's client_id, or null for a session. */\n    identifier?: string | null;\n    /** The API key's label or the application's name, or null when there is none. */\n    label?: string | null;\n    /** When the API key was last regenerated or the access token was issued, or null for a session. */\n    lastRegeneratedAt?: string | null;\n    /** The organization the credential acts in. */\n    organization?: SparseOrganization;\n    /** The person the credential acts for. */\n    person?: SparsePerson;\n    scopes?: string[];\n    /** The kind of credential. */\n    type?: CredentialType;\n}\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type TransientState = \"all\" | \"false\" | \"true\";\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type TransitStatus = \"IN_TRANSIT\" | \"IN_TRANSIT_TO_FIELD\" | \"IN_TRANSIT_TO_INVENTORY\" | \"NOT_IN_TRANSIT\";\n\nexport interface URLLink {\n    /** When the link was created. */\n    createdAt?: string;\n    /** The URL link's unique identifier. */\n    id?: string;\n    /** The URL link's key, which the URL link endpoints take as linkKey. */\n    key?: string;\n    /** The link's display name, or null when the link shows its address instead. */\n    name?: string | null;\n    /** When the link was last changed. */\n    updatedAt?: string;\n    /** The address the link points to. */\n    url?: string;\n}\n\n/** The unit a quantity is counted in, sent as its UNECE Recommendation 20 code. Accepted in any case. The listed spelling is the one the API sends back. | Value | Description | | --- | --- | | `BG` | Bag | | `BO` | Bottle | | `BX` | Box | | `C62` | Unit | | `CMK` | Square centimeter (cm2) | | `CMT` | Centimeter (cm) | | `CR` | Crate | | `CS` | Case | | `CT` | Carton | | `DMQ` | Cubic decimeter (dm3) | | `DR` | Drum | | `DZN` | Dozen (doz) | | `EA` | Each (ea) | | `EN` | Envelope | | `FOT` | Foot (ft) | | `FTK` | Square foot (ft2) | | `FTQ` | Cubic foot (ft3) | | `GLL` | Gallon (gal) | | `GRM` | Gram (g) | | `GRO` | Gross | | `H87` | Piece (pc) | | `INH` | Inch (in) | | `INK` | Square inch (in2) | | `INQ` | Cubic inch (in3) | | `KG` | Keg | | `KGM` | Kilogram (kg) | | `KMT` | Kilometer (km) | | `KT` | Kit | | `LBR` | Pound (lb) | | `LO` | Lot | | `LTR` | Liter (L) | | `MGM` | Milligram (mg) | | `MLT` | Milliliter (mL) | | `MMK` | Square millimeter (mm2) | | `MMT` | Millimeter (mm) | | `MTK` | Square meter (m2) | | `MTQ` | Cubic meter (m3) | | `MTR` | Meter (m) | | `ONZ` | Ounce (oz) | | `OZA` | Fluid ounce (fl oz) | | `PK` | Pack | | `PR` | Pair (pr) | | `PTI` | Pint (pt) | | `PX` | Pallet | | `QTI` | Quart (qt) | | `RL` | Reel | | `RO` | Roll | | `SET` | Set | | `SMI` | Mile (mi) | | `ST` | Sheet | | `STN` | Ton US (NT) | | `SV` | Skid | | `TNE` | Tonne metric (t) | | `TU` | Tube | | `YDK` | Square yard (yd2) | | `YDQ` | Cubic yard (yd3) | | `YRD` | Yard (yd) | */\nexport type UnitOfMeasure = \"BG\" | \"BO\" | \"BX\" | \"C62\" | \"CMK\" | \"CMT\" | \"CR\" | \"CS\" | \"CT\" | \"DMQ\" | \"DR\" | \"DZN\" | \"EA\" | \"EN\" | \"FOT\" | \"FTK\" | \"FTQ\" | \"GLL\" | \"GRM\" | \"GRO\" | \"H87\" | \"INH\" | \"INK\" | \"INQ\" | \"KG\" | \"KGM\" | \"KMT\" | \"KT\" | \"LBR\" | \"LO\" | \"LTR\" | \"MGM\" | \"MLT\" | \"MMK\" | \"MMT\" | \"MTK\" | \"MTQ\" | \"MTR\" | \"ONZ\" | \"OZA\" | \"PK\" | \"PR\" | \"PTI\" | \"PX\" | \"QTI\" | \"RL\" | \"RO\" | \"SET\" | \"SMI\" | \"ST\" | \"STN\" | \"SV\" | \"TNE\" | \"TU\" | \"YDK\" | \"YDQ\" | \"YRD\";\n\n/** Accepted in any case. The listed spelling is the one the API sends back. */\nexport type UsefulLifeRevisionReason = \"CHANGE_IN_USE\" | \"DAMAGE\" | \"OBSOLESCENCE\" | \"OTHER\" | \"REASSESSMENT\" | \"REFURBISHMENT\" | \"REGULATORY\";\n";
+//#endregion
+//#region src/command/types.ts
+const typesCommand = defineCommand({
+	name: "types",
+	summary: "Print TypeScript types for the Hardfin API",
+	description: `Writes a declaration for every record the API sends and takes, for API version ${API_VERSION}, which is the version this CLI calls. Regenerate them after upgrading the CLI.`,
+	arguments: [],
+	flags: [{
+		name: "output",
+		description: "Where to write the declarations, instead of standard output",
+		valueName: "path",
+		schema: z.string()
+	}, {
+		name: "json",
+		description: "Print machine-readable output, which is the default when stdout is not a terminal",
+		schema: z.boolean()
+	}],
+	examples: [{
+		description: "Write them into a project",
+		command: "hardfin types --output src/hardfin-api.d.ts"
+	}, {
+		description: "Read them",
+		command: "hardfin types | less"
+	}],
+	run: runTypes
+});
+async function runTypes(input) {
+	const output = input.flags["output"];
+	if (typeof output !== "string") {
+		process.stdout.write(API_TYPES);
+		return ExitCode.OK;
+	}
+	writeFileSync(output, API_TYPES);
+	writeData(input.isJSON ? {
+		written: output,
+		apiVersion: API_VERSION,
+		bytes: Buffer.byteLength(API_TYPES)
+	} : `Wrote ${output}`);
+	return ExitCode.OK;
+}
+//#endregion
 //#region src/auth/device.ts
 const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
 /** The interval a server gives is in seconds, and five more are added on a slow_down. */
@@ -2742,7 +2944,7 @@ async function report(error, occasion, resolved) {
 		const settings = resolved ?? toResolved();
 		const status = settings ? await toStatus(settings) : void 0;
 		const secrets = [settings?.settings.apiKey, settings ? toCredential(settings.settings.issuerUrl)?.refreshToken : void 0];
-		return await (await import("./sentry-CLaeAWNa.js")).send({
+		return await (await import("./sentry-BM9Rvhhy.js")).send({
 			error,
 			occasion,
 			telemetry,
@@ -3528,6 +3730,7 @@ const commands = [
 	loginCommand,
 	logoutCommand,
 	statusCommand,
+	initCommand,
 	...[
 		{
 			name: "asset",
@@ -6192,6 +6395,7 @@ const commands = [
 		}
 	],
 	apiCommand,
+	typesCommand,
 	configCommand,
 	agentGuideCommand,
 	completionCommand,
@@ -6330,5 +6534,5 @@ async function toReported(error, isJSON, resolved, level = "error") {
 //#endregion
 export { toCli, toParseExitCode, toReported, wasReportAttempted };
 
-//# sourceMappingURL=program-BdRDIa3u.js.map
-//# debugId=6057a656-73c2-55b1-9f09-873e3b83b368
+//# sourceMappingURL=program-CjKwnPeY.js.map
+//# debugId=5a591d32-0d31-5357-b447-e33420753351

package/dist/{sentry-CLaeAWNa.js → sentry-BM9Rvhhy.js}

@@ -1,10 +1,10 @@
 #!/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]="853940c3-9e72-566b-ad70-9f043e6aba8d")}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]="35c80804-dcd8-5662-9f00-9c8ff04f286a")}catch(e){}}();
 import { n as toScrubbed } from "./scrub-BN3gyBpR.js";
 import { dirname } from "node:path";
-import { request } from "node:http";
 import { fileURLToPath } from "node:url";
+import { request } from "node:http";
 import { request as request$1 } from "node:https";
 //#region node_modules/@sentry/core/build/esm/debug-build.js
 const DEBUG_BUILD = typeof __SENTRY_DEBUG__ === "undefined" || __SENTRY_DEBUG__;
@@ -3925,7 +3925,7 @@ function trim(arr) {
 	if (start > end) return [];
 	return arr.slice(start, end - start + 1);
 }
-function relative(from, to) {
+function relative$1(from, to) {
 	from = resolve$1(from).slice(1);
 	to = resolve$1(to).slice(1);
 	const fromParts = trim(from.split("/"));
@@ -4001,7 +4001,7 @@ function generateIteratee({ isBrowser, root, prefix }) {
 			}
 		} else if (isWindowsFrame || startsWithSlash) {
 			const filename = isWindowsFrame ? frame.filename.replace(/^[a-zA-Z]:/, "").replace(/\\/g, "/") : frame.filename;
-			frame.filename = `${prefix}${root ? relative(root, filename) : basename$1(filename)}`;
+			frame.filename = `${prefix}${root ? relative$1(root, filename) : basename$1(filename)}`;
 		}
 		return frame;
 	};
@@ -4385,5 +4385,5 @@ function toTags(delivery) {
 //#endregion
 export { send };
 
-//# sourceMappingURL=sentry-CLaeAWNa.js.map
-//# debugId=853940c3-9e72-566b-ad70-9f043e6aba8d
+//# sourceMappingURL=sentry-BM9Rvhhy.js.map
+//# debugId=35c80804-dcd8-5662-9f00-9c8ff04f286a

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hardfin/cli",
-    "version": "0.1.0-dev.35",
+    "version": "0.1.0-dev.37",
     "description": "Command line interface for the Hardfin API",
     "license": "Apache-2.0",
     "author": "Hardfin, Inc.",
@@ -24,7 +24,9 @@
     },
     "files": [
         "dist",
-        "!dist/**/*.map"
+        "!dist/**/*.map",
+        "skills",
+        "templates"
     ],
     "engines": {
         "node": ">=20"

package/skills/hardfin-cli/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: hardfin-cli
+description: Read and change records in a Hardfin organization with the Hardfin CLI (`hardfin`) - assets, customers, items, locations, files, ownership and moves. Use when the person asks to look up, import, create, update, move, scrap or archive Hardfin data, to sign in to Hardfin, or to check what the CLI is connected to. Not for writing application code that calls the Hardfin API over HTTP; read https://docs.hardfin.com for that.
+---
+
+# Hardfin CLI
+
+The `hardfin` command reads and changes the records in one Hardfin organization through the
+Hardfin API. Every API operation is a command, named `hardfin <noun> <verb>`.
+
+This skill gives the patterns. The installed CLI is the authority on exact commands and
+flags, so check `--help` before relying on a flag this skill does not show.
+
+## 1. Make sure the CLI is installed
+
+```sh
+hardfin --version || npm install -g @hardfin/cli
+```
+
+It needs Node 20 or later. If `npm install -g` is refused, run commands as
+`npx -y @hardfin/cli <command>` instead.
+
+## 2. Make sure it is signed in
+
+```sh
+hardfin status --offline --json
+```
+
+`credential.kind` is `none` when nobody is signed in. Then sign in one of three ways.
+
+| Situation                                                  | Do this                                          |
+| ---------------------------------------------------------- | ------------------------------------------------ |
+| You run on the person's own machine                        | Run `hardfin login` in the foreground            |
+| You run in a cloud sandbox, away from the person's browser | Run `hardfin login --device`                     |
+| The person gave you an API key                             | Pass `--api-key <key>`, or set `HARDFIN_API_KEY` |
+
+`hardfin login` writes one JSON line on stderr before it waits:
+
+- `{"event": "sign_in_url", "url": …, "browserOpened": …}`: show the person `url`, and say
+  whether a browser tab opened
+- `{"event": "device_code", "userCode": …, "verificationUri": …}`: show the person the code
+  and where to enter it
+
+It then waits up to `waitSeconds` (300) for the person to approve. Give the command that
+long to finish. Do not run it in the background and move on.
+
+Never write an API key into a file in the repository, and never echo it back.
+
+## 3. Find the command
+
+```sh
+hardfin --help                    # the nouns
+hardfin asset --help              # what you can do with assets
+hardfin asset create --help       # every flag that command takes
+hardfin agent-guide               # every command, flag, exit code and error code, as Markdown
+```
+
+| Noun               | Holds                                                                              |
+| ------------------ | ---------------------------------------------------------------------------------- |
+| `asset`            | Physical assets, with their accounting, events, files, moves, ownership and status |
+| `customer`         | The customers assets are sold or leased to                                         |
+| `item`             | The catalogue of item types an asset is an instance of                             |
+| `location`         | Warehouses, sites and their zones                                                  |
+| `file`, `url-link` | Attachments, and links to records elsewhere                                        |
+| `token`            | What the current credential is                                                     |
+| `api`              | Any endpoint directly, when no command fits                                        |
+
+## 4. Keys and IDs
+
+A record has both, and they are not interchangeable.
+
+|     | Looks like                                      | Used for                                                                             |
+| --- | ----------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Key | `ast_4f9xk2mq7plr8stz`, `item_V1StGXR8Z5jdHi6B` | The positional argument of `get`, `update` and nested commands                       |
+| ID  | `0192f7d4-3b6a-7c1e-9f2d-5a8b4c6e7d70`          | A field that points at another record, such as `--customer-id` or `--move assetId=…` |
+
+A list or get answers with both. Take the one the next command asks for.
+
+## 5. Read
+
+```sh
+hardfin asset list --limit 20 --search-query "RX-200"
+hardfin asset get ast_4f9xk2mq7plr8stz
+hardfin customer list --page 2 --limit 100
+```
+
+Output is JSON on stdout whenever stdout is not a terminal, so pipe it to `jq` or parse it.
+A list holds at most 100 records a page. Fetch every page before saying how many there are.
+
+## 6. Change
+
+Before any change:
+
+1. Read the record you are about to change, and work from what it says now
+2. For more than a few records, or anything that deletes, scraps or archives, tell the person
+   what will change and wait for them to agree
+3. Make the change
+4. Read the record back to confirm it
+
+Set fields with one flag each, or send the whole body as JSON with `--input`:
+
+```sh
+hardfin customer create --name "Acme"
+echo '{"name": "Dock 4, north side"}' | hardfin location create --input -
+hardfin asset accounting update ast_4f9xk2mq7plr8stz --unset useful-life
+```
+
+A flag given with `--input` replaces that field of the body. A value with a comma in it
+must go through `--input`, because a `key=value` flag cannot carry one.
+
+## 7. When a command fails
+
+The exit code says what kind of failure it was.
+
+| Exit code | Means                             | Do this                                        |
+| --------- | --------------------------------- | ---------------------------------------------- |
+| 0         | It worked                         |                                                |
+| 1         | The API or the network refused it | Read the error's `code`                        |
+| 2         | The command was called wrongly    | Run the command with `--help` and fix the call |
+| 4         | No usable credential              | Sign in, as in step 2                          |
+
+The error is JSON on stderr. Branch on its `code`, never on the message.
+
+| `code`                                              | Do this                                                          |
+| --------------------------------------------------- | ---------------------------------------------------------------- |
+| `not_signed_in`, `unauthorized`                     | Sign in again                                                    |
+| `invalid_flag`, `missing_flag`, `invalid_arguments` | Read `--help` for that command                                   |
+| `not_found`                                         | Check you passed a key, not an ID, where the command wants a key |
+| `bad_request`, `invalid_request`, `conflict`        | Read `errors`, which names the field                             |
+| `rate_limited`                                      | Wait a minute, then retry once                                   |
+| `unreachable`, `server_error`                       | Tell the person, and include `requestId` if there is one         |
+
+`hardfin agent-guide` lists every code.

package/templates/AGENTS.md

@@ -0,0 +1,25 @@
+## Hardfin
+
+This project works with Hardfin data through the Hardfin CLI, `hardfin`.
+
+| Task                               | Command                                                                      |
+| ---------------------------------- | ---------------------------------------------------------------------------- |
+| Install                            | `npm install -g @hardfin/cli`, with Node 20 or later                         |
+| Sign in                            | `hardfin login`, or `--device` away from a browser, or set `HARDFIN_API_KEY` |
+| Check what it is connected to      | `hardfin status`                                                             |
+| Find a command                     | `hardfin --help`, then `hardfin <noun> --help`                               |
+| Every command, flag and error code | `hardfin agent-guide`                                                        |
+| The API reference                  | https://docs.hardfin.com                                                     |
+
+Start with the `hardfin-cli` skill in `.agents/skills/hardfin-cli/SKILL.md`.
+
+The Hardfin MCP server, `{{MCP_URL}}`, is configured for Claude Code in `.mcp.json`, for
+Cursor in `.cursor/mcp.json`, and for VS Code in `.vscode/mcp.json`. For Codex, add
+`[mcp_servers.hardfin]` with `url = "{{MCP_URL}}"` to `~/.codex/config.toml`.
+
+Rules:
+
+- Read a record before changing it, and read it back afterwards
+- Ask the person before a bulk change, or anything that deletes, scraps or archives
+- Never write an API key into a file in this repository
+- Branch on an error's `code`, never on its message