driggsby 0.8.0 → 0.9.0

package/README.md

@@ -131,6 +131,26 @@ saved or refused on its own, and the JSON result says which and why.
 `items delete` needs `--yes`. Read items back with
 `npx driggsby@latest query query_item_sql --sql "..."`.
 
+## Statement imports
+
+Every import names its account, so Driggsby never picks one for you:
+
+```sh
+npx driggsby@latest accounts list
+npx driggsby@latest import statement.csv --account acct_7kq2
+npx driggsby@latest import statement.csv --create-account --account-type card --account-name "Everyday Card"
+```
+
+`accounts list` shows each account's ID. `--create-account` makes a new
+account (`card` or `bank`) with that name; a name an account already has is
+refused with that account's ID, so a script names it by ID from then on.
+An import returns at once with an ID; `npx driggsby@latest import <ID> --wait`
+follows it until the transactions are in. Every output ends with the exact
+command to run next, including one command per answer when Driggsby needs a
+fact it can't read from the file. Importing the same file again is safe: it
+shows where that import stands. `import undo <ID>` shows what undoing would
+remove (`--yes` does it), and `import list` lists your recent imports.
+
 ## License
 
 Apache-2.0. The bundled Inter font (`assets/Inter.woff2`), which

package/dist/args-import.js

@@ -0,0 +1,211 @@
+// Argv parsing for `driggsby import`: `import <FILE>` with the account it
+// goes in (--account, or --create-account with its type and name), `import
+// <ID>` with --wait and one answer flag, `import undo <FILE or ID> [--yes]`,
+// `import list`, and `accounts list`.
+// Same contract as the rest of the tree: help on -h/--help, usage errors
+// exit 2 and name the fix, echoed argv is sanitized, and "--" ends options
+// (so a file whose name starts with "-" still imports).
+import { helpCommand, unexpectedArgument } from "./args-shared.js";
+import { CliError } from "./cli-error.js";
+import { ACCOUNTS_HELP, IMPORT_HELP } from "./help.js";
+import {} from "./import/import-command.js";
+import { sanitizeForTerminal } from "./terminal-text.js";
+export const IMPORT_USAGE = "Usage: npx driggsby@latest import <FILE or ID> [--wait] [--account <ID> | --create-account --account-type <card|bank> --account-name <NAME>]";
+const UNDO_USAGE = "Usage: npx driggsby@latest import undo <FILE or ID> [--yes]";
+const LIST_USAGE = "Usage: npx driggsby@latest import list";
+const ACCOUNTS_USAGE = "Usage: npx driggsby@latest accounts list";
+const ANSWER_VALUES = {
+    "--dates": ["day-first", "month-first"],
+    "--amounts": ["positive-is-out", "positive-is-in"],
+};
+const ACCOUNT_VALUE = /^acct_[A-Za-z0-9_-]{1,64}$/;
+const ACCOUNT_TYPES = ["card", "bank"];
+const NAME_LIMIT = 100;
+export function parseAccounts(argv) {
+    const [first, ...rest] = argv;
+    if (first === undefined || first === "-h" || first === "--help") {
+        return helpCommand(ACCOUNTS_HELP);
+    }
+    if (first !== "list") {
+        throw unexpectedArgument(first, ACCOUNTS_USAGE);
+    }
+    for (const token of rest) {
+        if (token === "-h" || token === "--help") {
+            return helpCommand(ACCOUNTS_HELP);
+        }
+        throw unexpectedArgument(token, ACCOUNTS_USAGE);
+    }
+    return { kind: "import", options: { action: "accounts" } };
+}
+export function parseImport(argv) {
+    const first = argv[0];
+    if (first === "list") {
+        return command(parseList(argv.slice(1)));
+    }
+    if (first === "undo") {
+        return command(parseUndo(argv.slice(1)));
+    }
+    return command(parseRun(argv));
+}
+function command(options) {
+    return "kind" in options ? options : { kind: "import", options };
+}
+function parseList(argv) {
+    for (const token of argv) {
+        if (token === "-h" || token === "--help") {
+            return helpCommand(IMPORT_HELP);
+        }
+        throw unexpectedArgument(token, LIST_USAGE);
+    }
+    return { action: "list" };
+}
+function parseUndo(argv) {
+    let target = null;
+    let yes = false;
+    let optionsEnded = false;
+    for (const token of argv) {
+        if (!optionsEnded && token === "--") {
+            optionsEnded = true;
+        }
+        else if (!optionsEnded && (token === "-h" || token === "--help")) {
+            return helpCommand(IMPORT_HELP);
+        }
+        else if (!optionsEnded && token === "--yes") {
+            yes = true;
+        }
+        else if (target === null && (optionsEnded || !token.startsWith("-"))) {
+            target = token;
+        }
+        else {
+            throw unexpectedArgument(token, UNDO_USAGE);
+        }
+    }
+    if (target === null) {
+        throw missing("<FILE or ID>", UNDO_USAGE);
+    }
+    return { action: "undo", target, yes };
+}
+function parseRun(argv) {
+    const found = { target: null, wait: false, account: null, create: false, type: null, name: null, dates: null, amounts: null };
+    let optionsEnded = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index] ?? "";
+        if (!optionsEnded && token === "--") {
+            optionsEnded = true;
+            continue;
+        }
+        if (!optionsEnded && (token === "-h" || token === "--help")) {
+            return helpCommand(IMPORT_HELP);
+        }
+        if (!optionsEnded && token === "--wait") {
+            found.wait = true;
+            continue;
+        }
+        if (!optionsEnded && token === "--create-account") {
+            found.create = true;
+            continue;
+        }
+        const flag = optionsEnded ? null : valueFlag(token);
+        if (flag !== null) {
+            const inline = token.includes("=") ? token.slice(token.indexOf("=") + 1) : null;
+            const value = inline ?? argv[index + 1];
+            if (inline === null) {
+                index += 1;
+            }
+            setValue(found, flag, value);
+            continue;
+        }
+        if (found.target === null && (optionsEnded || !token.startsWith("-"))) {
+            found.target = token;
+            continue;
+        }
+        throw unexpectedArgument(token, IMPORT_USAGE);
+    }
+    if (found.target === null) {
+        throw missing("<FILE or ID>", IMPORT_USAGE);
+    }
+    return { action: "run", target: found.target, wait: found.wait, account: found.account, create: checkedCreate(found), dates: found.dates, amounts: found.amounts };
+}
+// The new account, whole, or a usage error naming what's missing; one way to
+// name the account, and an account flag never alongside an answer.
+function checkedCreate(found) {
+    if (found.account !== null && found.create) {
+        throw usage("name an existing account (--account) or a new one (--create-account), not both");
+    }
+    if (!found.create && (found.type !== null || found.name !== null)) {
+        throw usage("--account-type and --account-name go with --create-account");
+    }
+    if ((found.account !== null || found.create) && (found.dates !== null || found.amounts !== null)) {
+        throw usage("--dates and --amounts answer an import's question; --account and --create-account start an import. Give one or the other");
+    }
+    if (!found.create) {
+        return null;
+    }
+    if (found.type === null || found.name === null) {
+        throw usage("--create-account needs --account-type <card|bank> and --account-name <NAME>");
+    }
+    return { type: found.type, name: found.name };
+}
+function valueFlag(token) {
+    const name = token.split("=", 1)[0];
+    return name === "--account" || name === "--account-type" || name === "--account-name" || name === "--dates" || name === "--amounts" ? name : null;
+}
+function setValue(found, flag, value) {
+    if (value === undefined || value.trim() === "" || value.trim().startsWith("--")) {
+        throw new CliError(`error: a value is required for '${flag}' but none was supplied\n\n${IMPORT_USAGE}\n\nFor more information, try '--help'.`, 2);
+    }
+    if (flag === "--account") {
+        if (!ACCOUNT_VALUE.test(value)) {
+            throw new CliError(`error: invalid value '${sanitizeForTerminal(value)}' for '--account': name the account by its ID, like acct_7kq2\n` +
+                `(npx driggsby@latest accounts list shows each one)\n\n${IMPORT_USAGE}\n\nFor more information, try '--help'.`, 2);
+        }
+        found.account = once(found.account, flag, value);
+        return;
+    }
+    if (flag === "--account-type") {
+        if (!ACCOUNT_TYPES.includes(value)) {
+            throw invalid(flag, value, ACCOUNT_TYPES);
+        }
+        found.type = once(found.type, flag, value);
+        return;
+    }
+    if (flag === "--account-name") {
+        const name = value.trim();
+        // Characters a terminal or Driggsby would drop are refused here, so the
+        // name a retry prints is the name the account gets.
+        if (name.length > NAME_LIMIT || sanitizeForTerminal(name) !== name || /\p{Cf}/u.test(name)) {
+            throw new CliError(`error: invalid value for '--account-name': give the account's name, up to ${String(NAME_LIMIT)} characters\n\n${IMPORT_USAGE}\n\n` +
+                "For more information, try '--help'.", 2);
+        }
+        found.name = once(found.name, flag, name);
+        return;
+    }
+    const allowed = ANSWER_VALUES[flag];
+    if (!allowed.includes(value)) {
+        throw invalid(flag, value, allowed);
+    }
+    if (found.dates !== null || found.amounts !== null) {
+        throw usage("give one answer at a time: --dates or --amounts");
+    }
+    if (flag === "--dates") {
+        found.dates = value;
+    }
+    else {
+        found.amounts = value;
+    }
+}
+function once(current, flag, value) {
+    if (current !== null) {
+        throw usage(`'${flag}' was given more than once`);
+    }
+    return value;
+}
+function invalid(flag, value, allowed) {
+    return new CliError(`error: invalid value '${sanitizeForTerminal(value)}' for '${flag}'\n  [possible values: ${allowed.join(", ")}]\n\n${IMPORT_USAGE}\n\nFor more information, try '--help'.`, 2);
+}
+function usage(problem) {
+    return new CliError(`error: ${problem}\n\n${IMPORT_USAGE}\n\nFor more information, try '--help'.`, 2);
+}
+function missing(argument, usage) {
+    return new CliError(`error: the following required arguments were not provided:\n  ${argument}\n\n${usage}\n\nFor more information, try '--help'.`, 2);
+}

package/dist/args-query.js

@@ -8,6 +8,8 @@ import { didYouMean } from "./clap-suggestions.js";
 import { CliError } from "./cli-error.js";
 import { APP_TOOL_ALLOWLIST } from "./dev/tool-allowlist.js";
 import { QUERY_HELP } from "./help.js";
+import { ITEM_ACTION_TOOLS } from "./items/item-actions.js";
+import { RULE_ACTION_TOOLS } from "./rules/rule-actions.js";
 import { quotedForTerminal, wrapNames } from "./terminal-text.js";
 // The tools that take SQL: --sql applies only to these, and a retry
 // line names --sql only for them.
@@ -106,9 +108,25 @@ function invalidParams() {
 function missingTool() {
     return new CliError(`error: the following required arguments were not provided:\n  <TOOL>\n\n${QUERY_USAGE}\n\nFor more information, try '--help'.`, 2);
 }
+// A tool with a command of its own (the items and rules actions): its
+// refusal names that command rather than a read tool that looks alike.
+function commandFor(tool) {
+    const commands = [["items", ITEM_ACTION_TOOLS], ["rules", RULE_ACTION_TOOLS]];
+    for (const [command, tools] of commands) {
+        const action = Object.keys(tools).find((name) => tools[name] === tool);
+        if (action !== undefined)
+            return `npx driggsby@latest ${command} ${action}`;
+    }
+    return undefined;
+}
 function unknownTool(tool) {
-    const similar = didYouMean(tool, [...APP_TOOL_ALLOWLIST]);
-    const tip = similar === undefined ? "" : `  tip: a similar tool exists: '${similar}'\n\n`;
+    const command = commandFor(tool);
+    const similar = command === undefined ? didYouMean(tool, [...APP_TOOL_ALLOWLIST]) : undefined;
+    const tip = command !== undefined
+        ? `  tip: run ${tool} with its own command:\n    ${command}\n\n`
+        : similar === undefined
+            ? ""
+            : `  tip: a similar tool exists: '${similar}'\n\n`;
     return new CliError(`error: ${quotedForTerminal(tool, 60)} isn't a tool a Driggsby app can call.\n` +
         `Apps can watch these read-only tools:\n` +
         `${wrapNames([...APP_TOOL_ALLOWLIST], "  ")}\n\n${tip}${QUERY_USAGE}\n\nFor more information, try '--help'.`, 2);

package/dist/args-shared.js

@@ -4,6 +4,7 @@
 // terminal through an echoed argument, tip, or usage line.
 import { CliError } from "./cli-error.js";
 import {} from "./mcp-setup/known-client.js";
+import {} from "./import/import-command.js";
 import {} from "./items/item-actions.js";
 import {} from "./rules/rule-actions.js";
 import { sanitizeForTerminal } from "./terminal-text.js";

package/dist/args.js

@@ -13,6 +13,7 @@ import { parseInit } from "./args-init.js";
 import { parseLogin } from "./args-login.js";
 import { parseMcpSetup } from "./args-mcp-setup.js";
 import { parseQuery } from "./args-query.js";
+import { parseAccounts, parseImport } from "./args-import.js";
 import { parseItems } from "./args-items.js";
 import { parseRules } from "./args-rules.js";
 import { removeDashesTip, similarArgumentTip, unexpectedArgument, unexpectedFlagValue, } from "./args-shared.js";
@@ -26,7 +27,7 @@ const MCP_USAGE = "Usage: npx driggsby@latest mcp <COMMAND>";
 const ROOT_LEVEL = {
     helpText: ROOT_HELP,
     usage: ROOT_USAGE,
-    subcommands: ["mcp", "login", "logout", "init", "dev", "deploy", "rollback", "versions", "delete", "query", "rules", "items"],
+    subcommands: ["mcp", "login", "logout", "init", "dev", "deploy", "rollback", "versions", "delete", "query", "rules", "items", "import", "accounts"],
     longFlags: ["help", "version"],
     subcommandFlags: [
         { name: "mcp", longFlags: ["help"] },
@@ -41,6 +42,8 @@ const ROOT_LEVEL = {
         { name: "query", longFlags: ["sql", "params", "help"] },
         { name: "rules", longFlags: ["params", "params-file", "yes", "help"] },
         { name: "items", longFlags: ["params", "params-file", "yes", "help"] },
+        { name: "import", longFlags: ["wait", "account", "create-account", "account-type", "account-name", "dates", "amounts", "yes", "help"] },
+        { name: "accounts", longFlags: ["help"] },
     ],
     usagePrefix: "npx driggsby@latest",
     hasVersion: true,
@@ -114,6 +117,10 @@ function dispatchSubcommand(name, rest) {
             return parseRules(rest);
         case "items":
             return parseItems(rest);
+        case "import":
+            return parseImport(rest);
+        case "accounts":
+            return parseAccounts(rest);
         case "setup":
             return parseMcpSetup(rest);
         default:
@@ -190,7 +197,17 @@ function unknownLongFlagAtLevel(level, token, remainingArgs) {
     return unexpectedArgument(shown, level.usage);
 }
 // Flags anywhere in the tree whose next token is their value, not a word.
-const VALUE_FLAGS = new Set(["--params", "--params-file", "--sql", "--to", "-s", "--scope"]);
+const VALUE_FLAGS = new Set([
+    "--params",
+    "--params-file",
+    "--sql",
+    "--to",
+    "-s",
+    "--scope",
+    "--account",
+    "--dates",
+    "--amounts",
+]);
 function firstTypedSubcommand(level, args) {
     return args.find((argument, index) => level.subcommands.includes(argument) && !VALUE_FLAGS.has(args[index - 1] ?? ""));
 }

package/dist/help.js

@@ -23,6 +23,8 @@ Commands:
   query     Run one Driggsby data tool and print its result as JSON.
   rules     Create, change, and delete your transaction rules.
   items     Save and remove the items behind your charges.
+  import    Import a bank or card statement (a CSV file) into your accounts.
+  accounts  List your accounts and the IDs an import names.
 
 Options:
   -h, --help     Print help
@@ -40,6 +42,8 @@ Examples:
   npx driggsby@latest query get_overview
   npx driggsby@latest rules describe
   npx driggsby@latest items describe
+  npx driggsby@latest accounts list
+  npx driggsby@latest import statement.csv --account acct_7kq2
 `;
 export const INIT_HELP = `Create a new Driggsby app in a new folder.
 
@@ -269,6 +273,68 @@ Examples:
   npx driggsby@latest items save --params-file order.json
   npx driggsby@latest items delete --params-file refs.json --yes
 `;
+export const IMPORT_HELP = `Import a bank or card statement (a CSV file) into your Driggsby accounts.
+
+Sign in first with npx driggsby@latest login.
+
+Usage:
+  npx driggsby@latest import <FILE> --account <ID> [--wait]
+  npx driggsby@latest import <FILE> --create-account --account-type <card|bank> --account-name <NAME> [--wait]
+  npx driggsby@latest import <ID> [--dates <ORDER> | --amounts <DIRECTION>] [--wait]
+  npx driggsby@latest import undo <FILE or ID> [--yes]
+  npx driggsby@latest import list
+
+Every import names its account: one you have, by its ID (npx driggsby@latest
+accounts list shows each), or a new one by its type and name. Driggsby never
+picks an account for you.
+
+How it goes:
+  1. import <FILE> uploads the file and returns right away with an ID.
+  2. import <ID> --wait waits up to 90 seconds for the next milestone:
+     the transactions are in, a question, a stop, or categories done.
+  3. If Driggsby needs a fact it can't read from the file, like which way
+     round its dates are, the output asks and lists one command per answer.
+  4. Once the transactions are in, categories fill in on their own. If
+     you need them, run --wait again; each run shows how far along.
+
+Safe to repeat: importing the same file again shows where it stands and
+never imports it twice. Transactions already in the account are skipped,
+so overlapping exports are fine. A new account's name must be one no
+account has: after the first import, name that account by its ID.
+
+Options:
+      --account <ID>          The account to import into, by its ID
+      --create-account        Import into a new account, made by this import
+      --account-type <TYPE>   With --create-account: card or bank
+      --account-name <NAME>   With --create-account: the new account's name
+      --dates <ORDER>         Answer its question: day-first or month-first
+      --amounts <DIRECTION>   Answer its question: positive-is-out or positive-is-in
+      --wait                  Wait up to 90 seconds for the next milestone
+      --yes                   With undo: undo without asking
+  -h, --help                  Print help
+
+Files: CSV, up to 10 MB and 25,000 rows.
+
+Examples:
+  npx driggsby@latest accounts list
+  npx driggsby@latest import statement.csv --account acct_7kq2
+  npx driggsby@latest import statement.csv --create-account --account-type card --account-name "Everyday Card"
+  npx driggsby@latest import list
+`;
+export const ACCOUNTS_HELP = `List your Driggsby accounts and the IDs an import names.
+
+Sign in first with npx driggsby@latest login.
+
+Usage:
+  npx driggsby@latest accounts list
+
+Options:
+  -h, --help  Print help
+
+Examples:
+  npx driggsby@latest accounts list
+  npx driggsby@latest import statement.csv --account acct_7kq2
+`;
 export const MCP_HELP = `Set up Driggsby MCP clients.
 
 Usage: npx driggsby@latest mcp <COMMAND>

package/dist/import/import-client.js

@@ -0,0 +1,215 @@
+// The import command's channel to Driggsby: one upload for a new file's
+// bytes (POST /statement-imports), and the CLI-only statement-import tools
+// on /mcp for everything else. The file never rides a tool call. Every
+// request carries the saved sign-in, which requireDeploySession has already
+// pinned to Driggsby itself, and never follows a redirect.
+import { CliError } from "../cli-error.js";
+import { SIGN_IN_AGAIN_MESSAGE } from "../deploy/api-session.js";
+import { callRuleTool } from "../rules/rules-rpc.js";
+import { capForTerminal } from "../terminal-text.js";
+import { asRecord, readImportView, readUndoPreview, refText } from "./import-view.js";
+// With a lookup ahead of it, inside a coding agent's 2-minute limit on one
+// command; a 10 MB file needs about 1 Mbit/s of upload to finish.
+const UPLOAD_TIMEOUT_MS = 90_000;
+// Each tool call answers in well under a second; this only bounds a hung one.
+const TOOL_TIMEOUT_MS = 15_000;
+const MAX_SERVER_MESSAGE_CHARS = 1_000;
+// Far past anyone's accounts; only bounds a server that never stops paging.
+const ACCOUNT_PAGES = 20;
+export const IMPORTS_NOT_AVAILABLE_MESSAGE = "This sign-in can't import statements. Sign in again and approve the request:\n" + "  npx driggsby@latest login";
+// An answer the CLI can't read; the command adds the same command to run again.
+export const TROUBLE = "Driggsby couldn't take that just now. Please try again in a minute.";
+// Driggsby said it was busy, timed out, or was briefly unavailable: the same
+// command again is the fix, which the command names, whatever `retryable`
+// says (every import command is safe to repeat). A limit that lasts longer
+// (a day's) is rate_limited with retryable: false and keeps its own words.
+export class DriggsbyBusy extends Error {
+}
+const TEMPORARY_KINDS = new Set(["busy", "timeout", "unavailable"]);
+function temporary(details) {
+    if (details === null)
+        return false;
+    if (details.kind === "rate_limited")
+        return details.retryable === true;
+    return details.retryable === true || (typeof details.kind === "string" && TEMPORARY_KINDS.has(details.kind));
+}
+// Where the file is meant to go rides along, so an import of it that went
+// to another account comes back refused, with that import.
+export async function findByFile(session, sha256, destination) {
+    return tool(session, "get_statement_import", { sha256, ...destinationArguments(destination) });
+}
+function destinationArguments(destination) {
+    if (destination === null)
+        return {};
+    return "account" in destination
+        ? { account: destination.account }
+        : { new_account_type: destination.create.type, new_account_name: destination.create.name };
+}
+export async function findByRef(session, importRef) {
+    return tool(session, "get_statement_import", { import_ref: importRef });
+}
+export async function answer(session, importRef, given) {
+    return tool(session, "answer_statement_import", { import_ref: importRef, ...given });
+}
+export async function undo(session, importRef, confirm) {
+    return tool(session, "undo_statement_import", confirm ? { import_ref: importRef, confirm: true } : { import_ref: importRef });
+}
+export async function list(session) {
+    const outcome = await callRuleTool(session, "list_statement_imports", {}, TOOL_TIMEOUT_MS);
+    if (outcome.kind === "refused" && temporary(asRecord(outcome.details))) {
+        throw new DriggsbyBusy();
+    }
+    if (outcome.kind !== "ok") {
+        throw new CliError(outcome.kind === "error" ? notAvailable(outcome.message) : outcome.message, 1);
+    }
+    const imports = asRecord(outcome.result)?.imports;
+    if (!Array.isArray(imports)) {
+        throw new CliError(TROUBLE, 1);
+    }
+    const entries = imports;
+    return entries.flatMap((entry) => {
+        const view = readImportView(entry);
+        return view === null ? [] : [view];
+    });
+}
+// The person's accounts, every page of them.
+export async function accounts(session) {
+    const rows = [];
+    let pageToken = null;
+    for (let page = 0; page < ACCOUNT_PAGES; page += 1) {
+        const outcome = await callRuleTool(session, "list_accounts", pageToken === null ? {} : { page_token: pageToken }, TOOL_TIMEOUT_MS);
+        if (outcome.kind === "refused" && temporary(asRecord(outcome.details))) {
+            throw new DriggsbyBusy();
+        }
+        if (outcome.kind !== "ok") {
+            throw new CliError(outcome.kind === "error" ? notAvailable(outcome.message) : outcome.message, 1);
+        }
+        const result = asRecord(outcome.result);
+        const listed = result?.linked_accounts;
+        if (!Array.isArray(listed)) {
+            throw new CliError(TROUBLE, 1);
+        }
+        const entries = listed;
+        rows.push(...entries.flatMap((entry) => accountRow(entry)));
+        pageToken = typeof result?.next_page_token === "string" && result.next_page_token !== "" ? result.next_page_token : null;
+        if (pageToken === null)
+            break;
+    }
+    return rows;
+}
+function accountRow(value) {
+    const record = asRecord(value);
+    const ref = refText(record?.account_ref);
+    const name = typeof record?.account_display_name === "string" ? record.account_display_name : null;
+    if (ref === null || name === null) {
+        return [];
+    }
+    const last4 = typeof record?.account_mask_last4 === "string" && /^\d{4}$/.test(record.account_mask_last4) ? record.account_mask_last4 : null;
+    return [{ ref, name, type: typeof record?.account_type === "string" ? record.account_type : "", last4 }];
+}
+export async function upload(session, file, destination) {
+    // Bare headers on purpose, as for /mcp: Driggsby refuses anything that
+    // looks like a browser call, and Node's fetch adds no Origin of its own.
+    const headers = {
+        "Content-Type": "application/octet-stream",
+        Authorization: `Bearer ${session.token}`,
+        "Driggsby-Filename": encodeURIComponent(file.name),
+    };
+    if ("account" in destination) {
+        headers["Driggsby-Account"] = destination.account;
+    }
+    else {
+        headers["Driggsby-New-Account-Type"] = destination.create.type;
+        headers["Driggsby-New-Account-Name"] = encodeURIComponent(destination.create.name);
+    }
+    const response = await fetch(new URL("/statement-imports", session.baseUrl), {
+        method: "POST",
+        headers,
+        body: file.bytes,
+        redirect: "error",
+        signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
+    });
+    if (response.status === 401) {
+        throw new CliError(SIGN_IN_AGAIN_MESSAGE, 1);
+    }
+    // A minute's limit, or Driggsby (or the way to it) briefly down.
+    if (response.status === 429 || response.status >= 500) {
+        throw new DriggsbyBusy();
+    }
+    const payload = await jsonBody(response);
+    const record = asRecord(payload);
+    if (response.status === 403 && record?.error === "cli_sign_in_required") {
+        throw new CliError(IMPORTS_NOT_AVAILABLE_MESSAGE, 1);
+    }
+    if (response.ok) {
+        const view = readImportView(record?.import);
+        if (view === null) {
+            throw new CliError(TROUBLE, 1);
+        }
+        return { kind: "import", view, created: response.status === 201, note: null, undo: null };
+    }
+    if ((response.status === 422 || response.status === 413) && typeof record?.error === "string") {
+        return {
+            kind: "refused",
+            code: record.error,
+            message: serverMessage(record.error_description),
+            account: takenAccount(record.account),
+            view: readImportView(record.import),
+        };
+    }
+    throw new CliError(TROUBLE, 1);
+}
+async function tool(session, name, toolArguments) {
+    const outcome = await callRuleTool(session, name, toolArguments, TOOL_TIMEOUT_MS);
+    if (outcome.kind === "error") {
+        throw new CliError(notAvailable(outcome.message), 1);
+    }
+    const details = asRecord(outcome.kind === "ok" ? outcome.result : outcome.details);
+    if (outcome.kind === "refused" && temporary(details)) {
+        throw new DriggsbyBusy();
+    }
+    if (outcome.kind === "refused") {
+        return {
+            kind: "refused",
+            code: typeof details?.code === "string" ? details.code : "refused",
+            message: outcome.message,
+            account: takenAccount(details?.account),
+            view: readImportView(details?.import),
+        };
+    }
+    const view = readImportView(details?.import);
+    if (view === null) {
+        throw new CliError(TROUBLE, 1);
+    }
+    return {
+        kind: "import",
+        view,
+        created: false,
+        note: typeof details?.note === "string" ? serverMessage(details.note) : null,
+        undo: readUndoPreview(details?.undo),
+    };
+}
+// The account a new account's name already belongs to, when Driggsby says.
+function takenAccount(value) {
+    const record = asRecord(value);
+    const ref = refText(record?.account_ref);
+    const type = typeof record?.account_type === "string" ? record.account_type : "";
+    return ref === null ? null : { ref, name: serverMessage(record?.name), type, last4: null };
+}
+// A sign-in from before imports (or an app's token) is told how to get them;
+// any other protocol error keeps its own words.
+function notAvailable(message) {
+    return /isn't available from the Driggsby CLI|Only a Driggsby CLI sign-in|Unknown tool/.test(message) ? IMPORTS_NOT_AVAILABLE_MESSAGE : message;
+}
+async function jsonBody(response) {
+    try {
+        const parsed = await response.json();
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function serverMessage(value) {
+    return typeof value === "string" ? capForTerminal(value, MAX_SERVER_MESSAGE_CHARS).trim() : "";
+}