@huggies/shit-1170-rex-engine-middleman 0.0.0-stage → 0.0.2

package/bin/shit-1170/api_shit_1170_tx_queue_accounts_delete.ts

@@ -0,0 +1,68 @@
+// ========================================
+// API_SHIT_1170_TX_QUEUE_ACCOUNTS_DELETE
+// runnable bin for DELETE /api/shit-1170/tx-queue/{queue_id}/accounts/
+// {account_id} via middleman. the middleman logs the framed request +
+// response, so this bin only adds a summary.
+//
+//   bun middleman/bin/shit-1170/api_shit_1170_tx_queue_accounts_delete.ts \
+//     --api-key shit_1170_abc123... \
+//     --queue-id 8f14e45f-ceea-467a-9b0d-2b1c2e6c1a11 \
+//     --account-id alice.near
+//
+// --- WHY --- the account id is a flag and not a positional: the
+// account has to be the one the api key belongs to, and naming it
+// next to the key says so.
+//
+// --- WHY --- the request carries NO BODY: the account to remove is in
+// the path, and the api key in the header says who is asking.
+// ========================================
+
+import { api_shit_1170_tx_queue_accounts_delete } from "@huggies/shit-1170-rex-engine-middleman";
+import { resolve_base_url } from "../fun/resolve_base_url";
+import { split_argv } from "../fun/split_argv";
+
+// --- CONFIG --------------------------------------------------------
+// used when no argv is supplied. the default is the local backend,
+// which binds 0.0.0.0:54733 (see shit_1170_port_fun.rs).
+const DEFAULT_BASE_URL = "http://127.0.0.1:54733";
+
+// the flags of this bin that take no value.
+const BOOLEAN_FLAGS: string[] = [];
+
+// --- argv ----------------------------------------------------------
+// argv[0] is bun, argv[1] is this script, so real args start at 2.
+const argv = process.argv.slice(2);
+const { flags } = split_argv(argv, { boolean_flags: BOOLEAN_FLAGS });
+
+// --- WHY --- the base url is resolved from the raw argv rather than
+// the split result: split_argv would put --base-url in the flags map,
+// and reading the raw argv keeps one rule for the url: it is never a
+// positional.
+const base_url = resolve_base_url(argv, DEFAULT_BASE_URL);
+
+const queue_id = flags.get("--queue-id");
+const account_id = flags.get("--account-id");
+if (queue_id === undefined || account_id === undefined) {
+  console.error(
+    "usage: api_shit_1170_tx_queue_accounts_delete.ts [--base-url <url>] " +
+      "--api-key <key> --queue-id <id> --account-id <account_id>",
+  );
+  process.exit(1);
+}
+
+const queue = await api_shit_1170_tx_queue_accounts_delete(
+  base_url,
+  queue_id,
+  account_id,
+  { api_key: flags.get("--api-key") },
+);
+
+console.log(
+  `TX QUEUE ${queue.queueId}: ${queue.transactions.length} transaction(s), ` +
+    `${queue.accounts.length} account(s)`,
+);
+for (const account of queue.accounts) {
+  console.log(`  ${account.accountId}  ${account.status}`);
+}
+// ========================================
+// copyright 2026 by sleet.near

package/bin/shit-1170/api_shit_1170_tx_queue_accounts_post.ts

@@ -0,0 +1,65 @@
+// ========================================
+// API_SHIT_1170_TX_QUEUE_ACCOUNTS_POST
+// runnable bin for POST /api/shit-1170/tx-queue/{queue_id}/accounts via
+// middleman. the middleman logs the framed request + response, so this
+// bin only adds a summary.
+//
+//   bun middleman/bin/shit-1170/api_shit_1170_tx_queue_accounts_post.ts \
+//     --api-key shit_1170_abc123... \
+//     --queue-id 8f14e45f-ceea-467a-9b0d-2b1c2e6c1a11 \
+//     --account-id alice.near
+//
+// --- WHY --- the account id is a flag and not a positional: the
+// account has to be the one the api key belongs to, and naming it
+// next to the key says so.
+// ========================================
+
+import { api_shit_1170_tx_queue_accounts_post } from "@huggies/shit-1170-rex-engine-middleman";
+import { resolve_base_url } from "../fun/resolve_base_url";
+import { split_argv } from "../fun/split_argv";
+
+// --- CONFIG --------------------------------------------------------
+// used when no argv is supplied. the default is the local backend,
+// which binds 0.0.0.0:54733 (see shit_1170_port_fun.rs).
+const DEFAULT_BASE_URL = "http://127.0.0.1:54733";
+
+// the flags of this bin that take no value.
+const BOOLEAN_FLAGS: string[] = [];
+
+// --- argv ----------------------------------------------------------
+// argv[0] is bun, argv[1] is this script, so real args start at 2.
+const argv = process.argv.slice(2);
+const { flags } = split_argv(argv, { boolean_flags: BOOLEAN_FLAGS });
+
+// --- WHY --- the base url is resolved from the raw argv rather than
+// the split result: split_argv would put --base-url in the flags map,
+// and reading the raw argv keeps one rule for the url: it is never a
+// positional.
+const base_url = resolve_base_url(argv, DEFAULT_BASE_URL);
+
+const queue_id = flags.get("--queue-id");
+const account_id = flags.get("--account-id");
+if (queue_id === undefined || account_id === undefined) {
+  console.error(
+    "usage: api_shit_1170_tx_queue_accounts_post.ts [--base-url <url>] " +
+      "--api-key <key> --queue-id <id> --account-id <account_id>",
+  );
+  process.exit(1);
+}
+
+const queue = await api_shit_1170_tx_queue_accounts_post(
+  base_url,
+  queue_id,
+  { accountId: account_id },
+  { api_key: flags.get("--api-key") },
+);
+
+console.log(
+  `TX QUEUE ${queue.queueId}: ${queue.transactions.length} transaction(s), ` +
+    `${queue.accounts.length} account(s)`,
+);
+for (const account of queue.accounts) {
+  console.log(`  ${account.accountId}  ${account.status}`);
+}
+// ========================================
+// copyright 2026 by sleet.near

package/bin/shit-1170/api_shit_1170_tx_queue_facets_get.ts

@@ -0,0 +1,68 @@
+// ========================================
+// API_SHIT_1170_TX_QUEUE_FACETS_GET
+// runnable bin for GET /api/shit-1170/tx-queue/facets via middleman.
+// the middleman logs the framed request + response, so this bin only
+// adds a summary.
+//
+//   bun middleman/bin/shit-1170/api_shit_1170_tx_queue_facets_get.ts \
+//     --limit 40
+//
+// the filters:
+//   --limit   how many contracts and how many accounts, default 40
+//
+// --- WHY --- the bin sends NO api key: the route is open, because the
+// facets are a summary of the open queue list. the key is passed when
+// there is one, and it is not demanded.
+//
+// --- WHY --- a number flag that is not a number is named here rather
+// than sent to the route to be clamped into silence.
+// ========================================
+
+import { api_shit_1170_tx_queue_facets_get } from "@huggies/shit-1170-rex-engine-middleman";
+import { resolve_base_url } from "../fun/resolve_base_url";
+import { split_argv } from "../fun/split_argv";
+
+// --- CONFIG --------------------------------------------------------
+// used when no argv is supplied. the default is the local backend,
+// which binds 0.0.0.0:54733 (see shit_1170_port_fun.rs).
+const DEFAULT_BASE_URL = "http://127.0.0.1:54733";
+
+// the flags of this bin that take no value.
+const BOOLEAN_FLAGS: string[] = [];
+
+// --- argv ----------------------------------------------------------
+// argv[0] is bun, argv[1] is this script, so real args start at 2.
+const argv = process.argv.slice(2);
+const { flags } = split_argv(argv, { boolean_flags: BOOLEAN_FLAGS });
+
+// --- WHY --- the base url is resolved from the raw argv rather than
+// the split result: split_argv would put --base-url in the flags map,
+// and reading the raw argv keeps one rule for the url: it is never a
+// positional.
+const base_url = resolve_base_url(argv, DEFAULT_BASE_URL);
+
+const limit_raw = flags.get("--limit");
+let limit: number | undefined;
+if (limit_raw !== undefined) {
+  const parsed = Number(limit_raw);
+  if (!Number.isFinite(parsed)) {
+    console.error(`--limit must be a number: ${limit_raw}`);
+    process.exit(1);
+  }
+  limit = parsed;
+}
+
+const facets = await api_shit_1170_tx_queue_facets_get(base_url, { limit });
+
+console.log(
+  `TX QUEUE FACETS: ${facets.contracts.length} contract(s), ` +
+    `${facets.accounts.length} account(s)`,
+);
+for (const contract of facets.contracts) {
+  console.log(`  contract  ${contract.contractId}  ${contract.count}`);
+}
+for (const account of facets.accounts) {
+  console.log(`  account   ${account.accountId}  ${account.count}`);
+}
+// ========================================
+// copyright 2026 by sleet.near

package/bin/shit-1170/api_shit_1170_tx_queue_get.ts

@@ -0,0 +1,99 @@
+// ========================================
+// API_SHIT_1170_TX_QUEUE_GET
+// runnable bin for GET /api/shit-1170/tx-queue via middleman. the
+// middleman logs the framed request + response, so this bin only adds
+// a summary.
+//
+//   bun middleman/bin/shit-1170/api_shit_1170_tx_queue_get.ts \
+//     --api-key shit_1170_abc123... \
+//     --account-id alice.near \
+//     --hide-sent
+//
+// the filters:
+//   --account-id    only the queues these accounts are on, comma separated
+//   --hide-sent     with the account, drop the ones it has already sent
+//   --contract-id   only the queues holding a tx for these contracts, comma separated
+//   --method        only the queues holding a tx for this method
+//   --limit         how many, default 50
+//   --cursor        where the page starts, default the first page
+//
+// --- WHY --- --hide-sent stands alone and takes no value: it is a
+// switch, and "hide sent = maybe" is not a thing.
+//
+// --- WHY --- the flag names are kebab-case and the query names are
+// snake_case: the flag is what a person types, the query is what the
+// route reads. `serde_urlencoded` matches the query key literally, so
+// the snake_case spelling is the one that goes on the wire.
+//
+// --- WHY --- --cursor and not --offset: the page is walked by a cursor
+// the backend hands out, and the cursor is opaque. there is no offset
+// to ask for, and the bin prints the next cursor so the next page can
+// be fetched with it.
+// ========================================
+
+import { api_shit_1170_tx_queue_get } from "@huggies/shit-1170-rex-engine-middleman";
+import { resolve_base_url } from "../fun/resolve_base_url";
+import { split_argv } from "../fun/split_argv";
+
+// --- CONFIG --------------------------------------------------------
+// used when no argv is supplied. the default is the local backend,
+// which binds 0.0.0.0:54733 (see shit_1170_port_fun.rs).
+const DEFAULT_BASE_URL = "http://127.0.0.1:54733";
+
+// the flags of this bin that take no value.
+const BOOLEAN_FLAGS = ["--hide-sent"];
+
+// --- argv ----------------------------------------------------------
+// argv[0] is bun, argv[1] is this script, so real args start at 2.
+const argv = process.argv.slice(2);
+const { flags, seen } = split_argv(argv, { boolean_flags: BOOLEAN_FLAGS });
+
+// --- WHY --- the base url is resolved from the raw argv rather than
+// the split result: split_argv would put --base-url in the flags map,
+// and reading the raw argv keeps one rule for the url: it is never a
+// positional.
+const base_url = resolve_base_url(argv, DEFAULT_BASE_URL);
+
+// --- THE NUMBERS -------------------------
+// a number flag that is not a number is a typo, and it is named here
+// rather than sent to the route to be clamped into silence.
+function number_flag_fun(name: string): number | undefined {
+  const raw = flags.get(name);
+  if (raw === undefined) return undefined;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) {
+    console.error(`${name} must be a number: ${raw}`);
+    process.exit(1);
+  }
+  return parsed;
+}
+
+const limit = number_flag_fun("--limit");
+const cursor = flags.get("--cursor");
+
+const list = await api_shit_1170_tx_queue_get(
+  base_url,
+  {
+    account_id: flags.get("--account-id"),
+    hide_sent: seen.has("--hide-sent") ? true : undefined,
+    contract_id: flags.get("--contract-id"),
+    method: flags.get("--method"),
+    limit,
+    cursor,
+  },
+  { api_key: flags.get("--api-key") },
+);
+
+console.log(`TX QUEUE LIST: ${list.items.length} of ${list.total} queue(s)`);
+for (const queue of list.items) {
+  console.log(
+    `  ${queue.queueId}  ${queue.transactions.length} tx  ` +
+      `${queue.accounts.length} account(s)  ${queue.what ?? "(no what)"}`,
+  );
+  for (const account of queue.accounts) {
+    console.log(`    ${account.accountId}  ${account.status}`);
+  }
+}
+console.log(`NEXT CURSOR: ${list.nextCursor ?? "(last page)"}`);
+// ========================================
+// copyright 2026 by sleet.near

package/bin/shit-1170/api_shit_1170_tx_queue_one_get.ts

@@ -0,0 +1,67 @@
+// ========================================
+// API_SHIT_1170_TX_QUEUE_ONE_GET
+// runnable bin for GET /api/shit-1170/tx-queue/{queue_id} via
+// middleman. the middleman logs the framed request + response, so this
+// bin only adds a summary.
+//
+//   bun middleman/bin/shit-1170/api_shit_1170_tx_queue_one_get.ts \
+//     --api-key shit_1170_abc123... \
+//     --queue-id 8f14e45f-ceea-467a-9b0d-2b1c2e6c1a11
+// ========================================
+
+import { api_shit_1170_tx_queue_one_get } from "@huggies/shit-1170-rex-engine-middleman";
+import { resolve_base_url } from "../fun/resolve_base_url";
+import { split_argv } from "../fun/split_argv";
+
+// --- CONFIG --------------------------------------------------------
+// used when no argv is supplied. the default is the local backend,
+// which binds 0.0.0.0:54733 (see shit_1170_port_fun.rs).
+const DEFAULT_BASE_URL = "http://127.0.0.1:54733";
+
+// the flags of this bin that take no value.
+const BOOLEAN_FLAGS: string[] = [];
+
+// --- argv ----------------------------------------------------------
+// argv[0] is bun, argv[1] is this script, so real args start at 2.
+const argv = process.argv.slice(2);
+const { flags } = split_argv(argv, { boolean_flags: BOOLEAN_FLAGS });
+
+// --- WHY --- the base url is resolved from the raw argv rather than
+// the split result: split_argv would put --base-url in the flags map,
+// and reading the raw argv keeps one rule for the url: it is never a
+// positional.
+const base_url = resolve_base_url(argv, DEFAULT_BASE_URL);
+
+const queue_id = flags.get("--queue-id");
+if (queue_id === undefined) {
+  console.error(
+    "usage: api_shit_1170_tx_queue_one_get.ts [--base-url <url>] --api-key <key> --queue-id <id>",
+  );
+  process.exit(1);
+}
+
+const queue = await api_shit_1170_tx_queue_one_get(base_url, queue_id, {
+  api_key: flags.get("--api-key"),
+});
+
+console.log(
+  `TX QUEUE ${queue.queueId}: ${queue.transactions.length} transaction(s), ` +
+    `${queue.accounts.length} account(s)`,
+);
+console.log(`  what: ${queue.what ?? "(none)"}`);
+console.log(`  when: ${queue.when ?? "(none)"}`);
+console.log(`  why:  ${queue.why ?? "(none)"}`);
+for (const transaction of queue.transactions) {
+  console.log(
+    `  #${transaction.position} ${transaction.contractId}.${transaction.method}` +
+      `  tx: ${transaction.txId}`,
+  );
+  console.log(`    args: ${JSON.stringify(transaction.args)}`);
+  for (const account of transaction.accounts) {
+    console.log(
+      `    ${account.accountId}  ${account.status}  ${account.txHash ?? "(no hash)"}`,
+    );
+  }
+}
+// ========================================
+// copyright 2026 by sleet.near

package/bin/shit-1170/api_shit_1170_tx_queue_post.ts

@@ -0,0 +1,243 @@
+// ========================================
+// API_SHIT_1170_TX_QUEUE_POST
+// runnable bin for POST /api/shit-1170/tx-queue via middleman. the
+// middleman logs the framed request + response, so this bin only adds
+// a summary.
+//
+// a queue_id is a BATCH of transactions. one flag per transaction, in
+// the order the flags are given, and that order is the order the
+// wallet signs them in:
+//
+//   bun middleman/bin/shit-1170/api_shit_1170_tx_queue_post.ts \
+//     --api-key shit_1170_abc123... \
+//     --contract-id ref.finance.near \
+//     --method ft_swap \
+//     --args '{"receiver_id":"alice.near"}' \
+//     --contract-id ref.finance.near \
+//     --method ft_resolve_transfer \
+//     --args '{"receiver_id":"alice.near"}' \
+//     --what "swap 100 USDC for NEAR" \
+//     --why "you asked for it" \
+//     --account alice.near
+//
+// --- WHY --- the bin takes --contract-id over and over and not a json
+// file: a file is tidier for a batch of five and harder for the common
+// case of one. the flag repeats, and the order is the order.
+//
+// --- WHY --- the argv is scanned RAW and not through split_argv: the
+// flags that repeat have to keep their ORDER, and a Map of
+// last-write-wins would lose every transaction but the last. so the
+// transaction flags are collected here, in the order they appear, and
+// the single-valued flags are read with split_argv.
+//
+// --- WHY --- the flags of one transaction are matched by POSITION and
+// not by name: a transaction is one contract, one method, one args, one
+// gas and one deposit. the nth --contract-id, the nth --method and the
+// nth --args are the nth transaction. that is what lets a caller leave
+// --gas or --deposit off one call and on the next.
+// ========================================
+
+import {
+  api_shit_1170_tx_queue_post,
+  type SHIT_1170_TX_QUEUE_TRANSACTION_REQUEST,
+} from "@huggies/shit-1170-rex-engine-middleman";
+import { resolve_base_url } from "../fun/resolve_base_url";
+import { split_argv } from "../fun/split_argv";
+
+// --- CONFIG --------------------------------------------------------
+// used when no argv is supplied. the default is the local backend,
+// which binds 0.0.0.0:54733 (see shit_1170_port_fun.rs).
+const DEFAULT_BASE_URL = "http://127.0.0.1:54733";
+
+// the flags that name the pieces of ONE transaction, in the order they
+// are collected.
+const TRANSACTION_FLAGS = [
+  "--contract-id",
+  "--method",
+  "--args",
+  "--gas",
+  "--deposit",
+] as const;
+
+// the flags that take no value.
+const BOOLEAN_FLAGS: string[] = [];
+
+// --- argv ----------------------------------------------------------
+// argv[0] is bun, argv[1] is this script, so real args start at 2.
+const argv = process.argv.slice(2);
+
+const { flags } = split_argv(argv, { boolean_flags: BOOLEAN_FLAGS });
+
+// --- WHY --- the base url is resolved from the raw argv rather than
+// the split result: split_argv would put --base-url in the flags map,
+// and reading the raw argv keeps one rule for the url: it is never a
+// positional.
+const base_url = resolve_base_url(argv, DEFAULT_BASE_URL);
+
+// --- THE BATCH ---------------------------
+// the transactions, in the order the flags were given.
+//
+// --- WHY --- the scan is over the RAW argv: the order of the repeated
+// flags IS the order of the transactions, and split_argv's map is
+// last-write-wins. so each occurrence is collected as it is found.
+const contract_ids: string[] = [];
+const methods: string[] = [];
+const args_list: string[] = [];
+const gases: string[] = [];
+const deposits: string[] = [];
+
+for (let i = 0; i < argv.length; i++) {
+  const token = argv[i];
+  if (token === undefined) continue;
+  // --- WHY --- a repeated flag is read from the raw argv instead of
+  // from the map, because the map only holds the LAST value.
+  const value = argv[i + 1];
+  if (value === undefined || value.startsWith("--")) continue;
+  switch (token) {
+    case "--contract-id":
+      contract_ids.push(value);
+      i++;
+      break;
+    case "--method":
+      methods.push(value);
+      i++;
+      break;
+    case "--args":
+      args_list.push(value);
+      i++;
+      break;
+    case "--gas":
+      gases.push(value);
+      i++;
+      break;
+    case "--deposit":
+      deposits.push(value);
+      i++;
+      break;
+    default:
+      break;
+  }
+}
+
+if (contract_ids.length === 0) {
+  console.error(
+    "usage: api_shit_1170_tx_queue_post.ts [--base-url <url>] --api-key <key> " +
+      "--contract-id <id> --method <name> [--args <json>] [--gas <gas>] [--deposit <deposit>] " +
+      "[--contract-id <id> --method <name> ...] [--what <text>] [--when <text>] " +
+      "[--why <text>] [--when-at <ms>] [--account <account_id> ...]",
+  );
+  process.exit(1);
+}
+
+if (contract_ids.length !== methods.length) {
+  console.error(
+    `api_shit_1170_tx_queue_post: every transaction needs a --contract-id and a --method ` +
+      `(${contract_ids.length} contract id(s), ${methods.length} method(s))`,
+  );
+  process.exit(1);
+}
+
+// the WHO — the accounts this batch is for. each one must be an
+// account the api key belongs to.
+const accounts: string[] = [];
+for (let i = 0; i < argv.length; i++) {
+  const token = argv[i];
+  if (token === undefined) continue;
+  const value = argv[i + 1];
+  if (value === undefined || value.startsWith("--")) continue;
+  if (token === "--account") {
+    accounts.push(value);
+    i++;
+  }
+}
+
+const transactions: SHIT_1170_TX_QUEUE_TRANSACTION_REQUEST[] = [];
+for (let i = 0; i < contract_ids.length; i++) {
+  const contract_id = contract_ids[i];
+  const method = methods[i];
+  if (contract_id === undefined || method === undefined) continue;
+
+  // --- WHY --- the args are parsed HERE and not on the backend: the
+  // args must be a json OBJECT, and an object is a thing you can check
+  // before the round trip. a string that is not json would come back as
+  // a 400 with a less useful message than this one.
+  const args_raw = args_list[i];
+  let args: Record<string, unknown> | undefined;
+  if (args_raw !== undefined) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(args_raw);
+    } catch {
+      console.error(
+        `api_shit_1170_tx_queue_post: the --args of transaction ${i} are not json: ${args_raw}`,
+      );
+      process.exit(1);
+    }
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      Array.isArray(parsed)
+    ) {
+      console.error(
+        `api_shit_1170_tx_queue_post: the --args of transaction ${i} must be a json object`,
+      );
+      process.exit(1);
+    }
+    args = parsed as Record<string, unknown>;
+  }
+
+  const transaction: SHIT_1170_TX_QUEUE_TRANSACTION_REQUEST = {
+    contractId: contract_id,
+    method,
+  };
+  if (args !== undefined) transaction.args = args;
+  const gas = gases[i];
+  if (gas !== undefined) transaction.gas = gas;
+  const deposit = deposits[i];
+  if (deposit !== undefined) transaction.deposit = deposit;
+  transactions.push(transaction);
+}
+
+const when_at_raw = flags.get("--when-at");
+let when_at: number | undefined;
+if (when_at_raw !== undefined) {
+  const parsed = Number(when_at_raw);
+  if (!Number.isFinite(parsed)) {
+    console.error(
+      `api_shit_1170_tx_queue_post: --when-at must be a number of milliseconds: ${when_at_raw}`,
+    );
+    process.exit(1);
+  }
+  when_at = parsed;
+}
+
+const api_key = flags.get("--api-key");
+
+const queue = await api_shit_1170_tx_queue_post(
+  base_url,
+  {
+    what: flags.get("--what"),
+    when: flags.get("--when"),
+    why: flags.get("--why"),
+    whenAt: when_at,
+    transactions,
+    accounts: accounts.length > 0 ? accounts : undefined,
+  },
+  { api_key },
+);
+
+console.log(
+  `TX QUEUE: ${queue.queueId}  ${queue.transactions.length} transaction(s), ` +
+    `${queue.accounts.length} account(s)`,
+);
+for (const transaction of queue.transactions) {
+  console.log(
+    `  #${transaction.position} ${transaction.contractId}.${transaction.method}` +
+      `  tx: ${transaction.txId}`,
+  );
+}
+console.log(
+  `  accounts: ${queue.accounts.map((one) => one.accountId).join(", ")}`,
+);
+// ========================================
+// copyright 2026 by sleet.near