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

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 sleet.near
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# @huggies/shit-1170-rex-engine-middleman
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+clean ts library for interacting with the shit-1170-rex-engine backend routes.
+
+```sh
+bun i
+bun run build
+# publish
+bun publish --dry-run
+bunx npm login
+bun publish --access public
+# other
+bun run typecheck
+bunx prettier . --write
+```
+
+---
+
+shit-1170-rex-engine
+<br/>
+https://shit-1170.com
+
+the base url is a parameter on every call: the frontend passes the
+origin of the page it is served from, a bin passes whatever backend it
+was told to talk to (`--base-url`).
+
+the routes covered here are the ones this backend owns:
+
+- `/api/shit-1170/*` - our own routes, nothing is proxied
+- `/api/trezu/*` - our proxy for the trezu api
+
+the third-party apis the app talks to are NOT here. the intear api, the
+intear dex backend and the rhea indexer each ship their own published
+middleman package, so there is one client per api and one place to keep
+it:
+
+- `@sleet-js/middleman-intear-api` - `https://api.intea.rs`
+- `@sleet-js/middleman-intear-dex-api` - `https://dex-backend.intear.tech`
+- `@sleet-js/middleman-rhea-api` - `https://api.rhea.finance`
+
+=====================
+<br/>
+copyright 2026 by sleet.near

package/bin/README.md

@@ -0,0 +1,38 @@
+# @huggies/shit-1170-rex-engine-middleman/bin
+
+cli bins for our own backend, called through this package's `src/`.
+every bin imports the middleman wrapper (never `fetch`), so the framed
+request/response block and the error handling are identical to what
+the frontend sees.
+
+the bins are grouped by the api they talk to, mirroring the
+middleman:
+
+- [`bin/shit-1170/`](./shit-1170/README.md) — our own backend, through
+  `src/`.
+- `bin/fun/` — bin primitives shared by the bins above.
+
+each group has its own README with the example run commands.
+
+the third-party apis are not binned here. the intear api, the intear
+dex backend and the rhea indexer each ship their own bins inside their
+published middleman package, so there is one bin per endpoint and one
+place to keep it:
+
+- `@sleet-js/middleman-intear-api` — `node_modules/@sleet-js/middleman-intear-api/bin`
+- `@sleet-js/middleman-intear-dex-api` — `node_modules/@sleet-js/middleman-intear-dex-api/bin`
+- `@sleet-js/middleman-rhea-api` — `node_modules/@sleet-js/middleman-rhea-api/bin`
+
+bins accept positional args and `--flag value` pairs; when argv is
+omitted, the defaults documented per bin are used. all commands are run
+from the project root.
+
+## NOTES
+
+- **a flag that takes no value is listed by its bin.** `split_argv`
+  takes the boolean flags as an argument, so `--desc` in one bin never
+  swallows a positional in another bin.
+
+========================================
+<br/>
+copyright 2026 by sleet.near

package/bin/fun/resolve_base_url.ts

@@ -0,0 +1,45 @@
+// ========================================
+// RESOLVE_BASE_URL
+// bin primitive that picks the backend base URL for a bin run. scan argv
+// for an explicit `--base-url <url>` flag; when present the flag value
+// wins, otherwise the bin's own DEFAULT_BASE_URL is returned.
+//
+// argv layout expected:
+//   ["--base-url", "http://my-host:54733", ...other args...]
+// only the FIRST `--base-url` flag wins here. NOTE: this differs from
+// split_argv, where a repeated flag is last-write-wins.
+//
+// exit-1 on a present-but-empty `--base-url` (a typo is more likely
+// than a deliberate empty override). does NOT validate the URL beyond
+// "non-empty" — the fetch in api_call() surfaces a malformed URL as a
+// network error.
+//
+// --- WHY --- the flag wins over the default and there is no env-var
+// fallback. every invocation must be explicit about which backend it
+// talks to, because the docker-mounted production vault and the local
+// dev backend are different boxes.
+// ========================================
+
+export function resolve_base_url(
+  argv: string[],
+  default_base_url: string,
+): string {
+  // ========================================
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (tok === "--base-url") {
+      const value = argv[i + 1];
+      if (value === undefined || value === "") {
+        console.error(
+          "resolve_base_url: --base-url was passed without a value",
+        );
+        process.exit(1);
+      }
+      return value;
+    }
+  }
+  return default_base_url;
+  // ========================================
+}
+// ========================================
+// copyright 2026 by sleet.near

package/bin/fun/split_argv.ts

@@ -0,0 +1,67 @@
+// ========================================
+// SPLIT_ARGV
+// bin primitive that separates positional args from flags in one pass,
+// so every bin parses argv the same way. a flag listed in the bin's own
+// boolean_flags takes no value; every other --flag takes the next token
+// as its value.
+//
+// booleans are recorded in the `seen` set rather than the flags map, so
+// a bin reads `seen.has("--desc")` instead of guessing whether the map
+// holds "true" or an empty string.
+//
+// --- WHY --- the boolean flags are per-bin, not one global set. the
+// shit-1170 bins use --include-hidden, and a shared set would make one
+// bin's flag swallow the next positional in another bin's argv.
+// ========================================
+
+export interface SPLIT_ARGV_OPTIONS {
+  // the flags that stand alone with no value.
+  boolean_flags?: Iterable<string>;
+}
+
+export interface SPLIT_ARGV_RESULT {
+  positional: string[];
+  flags: Map<string, string>;
+  // true when the flag appeared in argv at all, boolean or not.
+  seen: Set<string>;
+}
+
+export function split_argv(
+  argv: string[],
+  options: SPLIT_ARGV_OPTIONS = {},
+): SPLIT_ARGV_RESULT {
+  const boolean_flags = new Set(options.boolean_flags ?? []);
+  const positional: string[] = [];
+  const flags = new Map<string, string>();
+  const seen = new Set<string>();
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    // --- WHY --- the guard: with `noUncheckedIndexedAccess` an index
+    // into an array reads as `string | undefined`, and the loop bound
+    // is not enough for the compiler to prove it. an empty argv skips
+    // the loop entirely, so this branch is unreachable in practice.
+    if (token === undefined) continue;
+    if (!token.startsWith("--")) {
+      positional.push(token);
+      continue;
+    }
+    seen.add(token);
+    if (boolean_flags.has(token)) continue;
+
+    const value = argv[i + 1];
+    // --- WHY --- a trailing flag with no value is a typo far more
+    // often than a deliberate empty string, and a value-taking flag
+    // must never swallow the next positional.
+    if (value === undefined || value.startsWith("--")) {
+      console.error(`split_argv: ${token} was passed without a value`);
+      process.exit(1);
+    }
+    flags.set(token, value);
+    i++;
+  }
+
+  return { positional, flags, seen };
+}
+// ========================================
+// copyright 2026 by sleet.near

package/bin/shit-1170/README.md

@@ -0,0 +1,333 @@
+# bin/shit-1170
+
+cli bins for our own backend, called through `middleman`.
+one bin per route of ours, so a new route gets a new bin.
+
+all commands are run from the project root.
+
+every bin takes `--base-url <url>` to point at a backend other than the
+default one (`http://127.0.0.1:54733`).
+
+## the api key
+
+the api key is the bearer token the user hands to an agent. it travels
+in the `x-api-key` header, and the legacy `x-session-token` header is
+sent alongside it during the beta.
+
+every bin that needs one takes `--api-key <key>`.
+
+## api_shit_1170_ping_get
+
+GET /api/shit-1170/ping — liveness check. answers
+`{ "ok": true, "app": "shit-1170" }`.
+
+```sh
+# defaults to http://127.0.0.1:54733
+bun middleman/bin/shit-1170/api_shit_1170_ping_get.ts
+
+# point at a different backend (staging / docker host / etc.)
+bun middleman/bin/shit-1170/api_shit_1170_ping_get.ts --base-url http://my-host:54733
+```
+
+## api_shit_1170_api_keys_post
+
+POST /api/shit-1170/api-keys — sign in and get an api key. the signed
+messages come from a json file, so a real signature can be posted
+without a wallet in the loop. the file holds the accounts array, either
+as the array itself or as the whole request body.
+
+```sh
+bun middleman/bin/shit-1170/api_shit_1170_api_keys_post.ts --accounts ./accounts.json
+```
+
+## api_shit_1170_api_key_me_get
+
+GET /api/shit-1170/api-key/me — which account the api key belongs to.
+
+```sh
+bun middleman/bin/shit-1170/api_shit_1170_api_key_me_get.ts --api-key shit_1170_abc123...
+```
+
+## api_shit_1170_api_key_rotate_post
+
+POST /api/shit-1170/api-key/rotate — give an account a NEW api key. the
+old key stops working at once. the signed message comes from a json
+file, the same way the sign-in bin takes it.
+
+```sh
+bun middleman/bin/shit-1170/api_shit_1170_api_key_rotate_post.ts --accounts ./accounts.json
+```
+
+## the tx queue
+
+a `queue_id` is a BATCH of transactions, not one transaction. the agent
+queues a swap that needs three calls, they go in together, and the user
+signs them as one batch in one wallet popup.
+
+## api_shit_1170_tx_queue_post
+
+POST /api/shit-1170/tx-queue — queue a batch of transactions.
+
+one flag per transaction, and the flag order IS the transaction order:
+the nth `--contract-id`, the nth `--method` and the nth `--args` are
+the nth transaction. `--gas` and `--deposit` are optional per call.
+
+`--account` names the WHO — the accounts the batch is for. each one
+must be an account the api key belongs to.
+
+```sh
+# queue ONE transaction
+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"}' \
+  --what "swap 100 USDC for NEAR" \
+  --why "you asked for it" \
+  --account alice.near
+
+# queue a BATCH of two, in order, in one wallet popup
+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"}' \
+  --gas 30000000000000 \
+  --deposit 1 \
+  --contract-id ref.finance.near \
+  --method ft_resolve_transfer \
+  --args '{"receiver_id":"alice.near"}' \
+  --when "when the price is right" \
+  --when-at 1772666400000
+```
+
+## api_shit_1170_tx_queue_get
+
+GET /api/shit-1170/tx-queue — the queue list, filterable.
+
+- `--account-id` — only the queues this account is on
+- `--hide-sent` — with the account, drop the ones it has already sent
+- `--contract-id` — only the queues holding a tx for this contract
+- `--method` — only the queues holding a tx for this method
+- `--limit` — how many, default 50
+- `--offset` — where to start, default 0
+
+`--hide-sent` stands alone, it takes no value. it needs `--account-id`
+— it is a filter on ONE account's view.
+
+```sh
+bun middleman/bin/shit-1170/api_shit_1170_tx_queue_get.ts --api-key shit_1170_abc123...
+bun middleman/bin/shit-1170/api_shit_1170_tx_queue_get.ts \
+  --api-key shit_1170_abc123... \
+  --account-id alice.near \
+  --hide-sent \
+  --limit 20
+```
+
+## api_shit_1170_tx_queue_one_get
+
+GET /api/shit-1170/tx-queue/{queue_id} — one queued batch, with its
+transactions and its accounts.
+
+```sh
+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
+```
+
+## api_shit_1170_tx_queue_accounts_post
+
+POST /api/shit-1170/tx-queue/{queue_id}/accounts — add YOUR OWN account
+to a queued batch. the api key must belong to that account.
+
+```sh
+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
+```
+
+## api_shit_1170_tx_queue_accounts_delete
+
+DELETE /api/shit-1170/tx-queue/{queue_id}/accounts/{account_id} —
+remove YOUR OWN account from a queued batch. a row that already carries
+a hash is history and is not deleted.
+
+```sh
+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
+```
+
+## api_shit_1170_tx_queue_sent_post
+
+POST /api/shit-1170/tx-queue/{queue_id}/sent — record that the
+transactions were sent.
+
+ONE call for the whole batch — the wallet sent every transaction in one
+popup, so the app reports every hash in one call. the flags repeat, and
+the nth `--tx-id`, the nth `--tx-hash` and the nth `--status` are the
+nth entry.
+
+`--status` is optional: without it the status is `sent`, which means
+"it went out and nobody knows how it went yet".
+
+```sh
+bun middleman/bin/shit-1170/api_shit_1170_tx_queue_sent_post.ts \
+  --api-key shit_1170_abc123... \
+  --queue-id 8f14e45f-ceea-467a-9b0d-2b1c2e6c1a11 \
+  --tx-id 1a2b3c4d-0000-0000-0000-000000000001 \
+  --tx-hash 9hN3lq... \
+  --status succeeded \
+  --tx-id 1a2b3c4d-0000-0000-0000-000000000002 \
+  --tx-hash AbCdEf... \
+  --status failed
+```
+
+## api_shit_1170_tx_queue_stats_contracts_get
+
+GET /api/shit-1170/tx-queue/stats/contracts — how many queued
+transactions hit each contract, biggest first.
+
+```sh
+bun middleman/bin/shit-1170/api_shit_1170_tx_queue_stats_contracts_get.ts \
+  --api-key shit_1170_abc123... \
+  --limit 20
+```
+
+## api_shit_1170_tx_queue_stats_methods_get
+
+GET /api/shit-1170/tx-queue/stats/methods — how many queued
+transactions call each method, biggest first. the contract rides along,
+because `ft_swap` on two contracts is two different transactions.
+
+```sh
+bun middleman/bin/shit-1170/api_shit_1170_tx_queue_stats_methods_get.ts \
+  --api-key shit_1170_abc123... \
+  --limit 20
+```
+
+## api_trezu_treasuries_get
+
+GET /api/trezu/user/treasuries — the treasuries (sputnik daos) an
+account belongs to. the account id is required and is trimmed.
+`--include-hidden` stands alone, it takes no value.
+
+```sh
+bun middleman/bin/shit-1170/api_trezu_treasuries_get.ts sleet.near
+bun middleman/bin/shit-1170/api_trezu_treasuries_get.ts sleet.near --include-hidden
+bun middleman/bin/shit-1170/api_trezu_treasuries_get.ts sleet.near --base-url http://my-host:54733
+```
+
+## the swap queue
+
+a `swap_id` is a SWAP, not a batch of transactions. the agent does not
+know the route — it names the token in, the amount in and the token out,
+and the route is worked out when the swap is executed.
+
+`--amount-in` is the RAW unit amount — the token's smallest unit — and
+not a human amount. a human amount only means something next to the
+token it belongs to.
+
+## api_shit_1170_swap_queue_post
+
+POST /api/shit-1170/swap-queue — queue a swap.
+
+`--account` names the WHO — the accounts the swap is for. each one must
+be an account the api key belongs to.
+
+```sh
+bun middleman/bin/shit-1170/api_shit_1170_swap_queue_post.ts \
+  --api-key shit_1170_abc123... \
+  --token-in usdt.tether-token.near \
+  --amount-in 100000000 \
+  --token-out near \
+  --what "swap 100 USDC for NEAR" \
+  --why "you asked for it" \
+  --account alice.near
+```
+
+## api_shit_1170_swap_queue_get
+
+GET /api/shit-1170/swap-queue — the swap list, filterable.
+
+- `--account-id` — only the swaps this account is on
+- `--hide-sent` — with the account, drop the ones it has already sent
+- `--token-in` — only the swaps that sell this token
+- `--token-out` — only the swaps that buy this token
+- `--limit` — how many, default 50
+- `--offset` — where to start, default 0
+
+`--hide-sent` stands alone, it takes no value. it needs `--account-id`
+— it is a filter on ONE account's view.
+
+```sh
+bun middleman/bin/shit-1170/api_shit_1170_swap_queue_get.ts --api-key shit_1170_abc123...
+bun middleman/bin/shit-1170/api_shit_1170_swap_queue_get.ts \
+  --api-key shit_1170_abc123... \
+  --account-id alice.near \
+  --hide-sent \
+  --limit 20
+```
+
+## api_shit_1170_swap_queue_one_get
+
+GET /api/shit-1170/swap-queue/{swap_id} — one queued swap, with its
+accounts.
+
+```sh
+bun middleman/bin/shit-1170/api_shit_1170_swap_queue_one_get.ts \
+  --api-key shit_1170_abc123... \
+  --swap-id 8f14e45f-ceea-467a-9b0d-2b1c2e6c1a11
+```
+
+## api_shit_1170_swap_queue_accounts_post
+
+POST /api/shit-1170/swap-queue/{swap_id}/accounts — add YOUR OWN
+account to a queued swap. the api key must belong to that account.
+
+```sh
+bun middleman/bin/shit-1170/api_shit_1170_swap_queue_accounts_post.ts \
+  --api-key shit_1170_abc123... \
+  --swap-id 8f14e45f-ceea-467a-9b0d-2b1c2e6c1a11 \
+  --account-id alice.near
+```
+
+## api_shit_1170_swap_queue_accounts_delete
+
+DELETE /api/shit-1170/swap-queue/{swap_id}/accounts/{account_id} —
+remove YOUR OWN account from a queued swap. a row that already carries a
+hash is history and is not deleted.
+
+```sh
+bun middleman/bin/shit-1170/api_shit_1170_swap_queue_accounts_delete.ts \
+  --api-key shit_1170_abc123... \
+  --swap-id 8f14e45f-ceea-467a-9b0d-2b1c2e6c1a11 \
+  --account-id alice.near
+```
+
+## api_shit_1170_swap_queue_sent_post
+
+POST /api/shit-1170/swap-queue/{swap_id}/sent — record that the swap
+was sent. THIS is the route the swap page calls after it executes a
+queued swap.
+
+a queued swap is ONE swap, so there is ONE hash and not a list.
+
+`--status` is optional: without it the status is `sent`, which means
+"it went out and nobody knows how it went yet". `--amount-out` is the
+amount that came out, in the output token's smallest unit.
+
+```sh
+bun middleman/bin/shit-1170/api_shit_1170_swap_queue_sent_post.ts \
+  --api-key shit_1170_abc123... \
+  --swap-id 8f14e45f-ceea-467a-9b0d-2b1c2e6c1a11 \
+  --tx-hash 9hN3lq... \
+  --status succeeded \
+  --amount-out 4999000000000000000000000
+```
+
+========================================
+<br/>
+copyright 2026 by sleet.near

package/bin/shit-1170/api_shit_1170_api_key_me_get.ts

@@ -0,0 +1,46 @@
+// ========================================
+// API_SHIT_1170_API_KEY_ME_GET
+// runnable bin for GET /api/shit-1170/api-key/me via middleman. the
+// middleman logs the framed request + response, so this bin only adds
+// a one-line summary.
+//
+//   bun middleman/bin/shit-1170/api_shit_1170_api_key_me_get.ts \
+//     --api-key shit_1170_abc123...
+//
+// --- WHY --- this is the bin that tells an agent whether the key it
+// holds is still good: a 401 means the key is not one of ours, and a
+// 200 names the account it belongs to.
+// ========================================
+
+import { api_shit_1170_api_key_me_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 me = await api_shit_1170_api_key_me_get(base_url, {
+  api_key: flags.get("--api-key"),
+});
+
+console.log(`API KEY ME: ${me.accountId}`);
+console.log(`  created: ${new Date(me.createdAt).toISOString()}`);
+console.log(`  updated: ${new Date(me.updatedAt).toISOString()}`);
+// ========================================
+// copyright 2026 by sleet.near

package/bin/shit-1170/api_shit_1170_api_key_rotate_post.ts

@@ -0,0 +1,83 @@
+// ========================================
+// API_SHIT_1170_API_KEY_ROTATE_POST
+// runnable bin for POST /api/shit-1170/api-key/rotate via middleman.
+// the middleman logs the framed request + response, so this bin only
+// adds a one-line summary.
+//
+// the accounts come from a json file, so a real signed message can be
+// posted without a wallet in the loop:
+//
+//   bun middleman/bin/shit-1170/api_shit_1170_api_key_rotate_post.ts \
+//     --accounts <path-to-json>
+//
+// the file holds ONE signed account, either as the array itself or as
+// the whole request body:
+//   { "accounts": [ { "accountId": "...", "publicKey": "...", ... } ] }
+//
+// --- WHY --- the rotation is proved by the SIGNED MESSAGE and not by
+// the old key: the old key is what a thief has. a rotation that only
+// needed the old key could be done by the thief, who would lock the
+// owner out while keeping access. the signed message proves the owner
+// still holds the account's NEAR key.
+//
+// --- WHY --- --api-key is optional here: the route proves the ownership
+// with the signed message, so the key is not needed. it is still sent
+// when it is given, because the header is the route's usual way of
+// saying who is calling.
+// ========================================
+
+import { readFileSync } from "node:fs";
+import { api_shit_1170_api_key_rotate_post } from "@huggies/shit-1170-rex-engine-middleman";
+import type {
+  SHIT_1170_API_KEYS_REQUEST,
+  SHIT_1170_SIGNED_ACCOUNT,
+} 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 accounts_flag = argv.indexOf("--accounts");
+const accounts_path =
+  accounts_flag === -1 ? undefined : argv[accounts_flag + 1];
+if (accounts_path === undefined || accounts_path.length === 0) {
+  console.error(
+    "usage: api_shit_1170_api_key_rotate_post.ts [--base-url <url>] --accounts <file.json>",
+  );
+  process.exit(1);
+}
+
+const raw = readFileSync(accounts_path, "utf8");
+const parsed = JSON.parse(raw) as
+  SHIT_1170_API_KEYS_REQUEST | SHIT_1170_SIGNED_ACCOUNT[];
+// the file may hold the accounts array on its own or the whole body.
+const accounts = Array.isArray(parsed) ? parsed : parsed.accounts;
+
+const key = await api_shit_1170_api_key_rotate_post(
+  base_url,
+  { accounts },
+  { api_key: flags.get("--api-key") },
+);
+
+console.log(`API KEY ROTATED: ${key.accountId}`);
+console.log(`  key: ${key.apiKey}`);
+console.log("  the old key stops working at once — update whatever holds it.");
+// ========================================
+// copyright 2026 by sleet.near