@floatonnear/float-adapter 0.2.1 → 0.3.0

package/dist/owner-plan.js

@@ -0,0 +1,112 @@
+import { planAddRole, planFreezeNode, planPurgeSettled, planSetCooldown, planSetNodeCaps, planSetPaused, planSetRecipients, planSetStrictAllocation, planWithdraw, } from "@floatonnear/mcp/payloads";
+/**
+ * The action name is not one we serve.
+ *
+ * A SEPARATE type from a bad argument, because the HTTP layer has to tell
+ * them apart: it used to catch every throw from here and report
+ * `unknown action: <name>`, so a negative cooldown or a duplicate recipient
+ * was reported as a method that does not exist - the one explanation that
+ * cannot lead the caller to a fix.
+ */
+export class UnknownActionError extends Error {
+    constructor(action) {
+        super(`unknown action: ${action}`);
+        this.name = "UnknownActionError";
+    }
+}
+/**
+ * A node-scoped action must name its node.
+ *
+ * THE TYPE SAYS `nodeId: number` AND THAT PROVES NOTHING AT RUNTIME. The body
+ * arrives as JSON and is cast, so a request that simply omits the field type-
+ * checks all the way through. Measured live on 2026-11-09:
+ * `{"action":"freeze"}` returned HTTP 200 with `args: {"frozen": false}` and
+ * the summary "Unfreeze node undefined" — `JSON.stringify` drops an undefined
+ * value, so `node_id` vanished from the args and from the CLI string, and the
+ * user was handed a confident command for a node that does not exist.
+ *
+ * It reverts rather than doing damage: `freeze_node(node_id: NodeId, ..)` uses
+ * `NodeId = u32` with no `#[serde(default)]`, so near-sdk fails to deserialize
+ * instead of falling back to `ROOT_NODE = 0`. Wasted gas and a confusing
+ * failure, not a silently frozen root.
+ *
+ * `!== "number"`, NOT `!b.nodeId`. Root is node 0 and 0 is falsy, so the
+ * obvious guard would refuse the node most likely to be frozen or re-capped.
+ * `NaN` is excluded too, because `JSON.parse` cannot produce it but a hand-
+ * built caller can, and `node_id: NaN` serialises to `null`.
+ */
+function requireNode(b) {
+    if (typeof b.nodeId !== "number" || !Number.isInteger(b.nodeId) || b.nodeId < 0) {
+        throw new Error(`action '${b.action}' needs nodeId: a non-negative integer naming the node to change. ` +
+            `Root is nodeId 0. Omitting it would build a command with no node_id at all, ` +
+            `which the contract refuses after the owner has already signed it.`);
+    }
+    return b.nodeId;
+}
+export function planOwnerAction(b, env) {
+    switch (b.action) {
+        case "caps":
+            // HUMAN units, with decimals — `planSetNodeCaps` scales them itself via
+            // limitsToArgs. Calling toBaseUnits here too would scale twice and turn
+            // a 100 USDC cap into 100 million USDC, which is not a cap at all.
+            return planSetNodeCaps(env.vault, requireNode(b), [
+                {
+                    token: env.token,
+                    dailyCap: b.dailyCap ?? "0",
+                    perTxCap: b.perTxCap ?? "0",
+                    decimals: env.decimals,
+                },
+            ]);
+        case "cooldown":
+            return planSetCooldown(env.vault, requireNode(b), b.cooldownSec ?? 0);
+        case "recipients":
+            // `?? null` is load-bearing: an absent list means INHERIT. Defaulting to
+            // `[]` would panic `validate_recipients`, which demands "1..=32
+            // recipients, or None to inherit".
+            return planSetRecipients(env.vault, requireNode(b), b.recipients ?? null);
+        case "freeze":
+            return planFreezeNode(env.vault, requireNode(b), b.frozen ?? false);
+        case "pause":
+            // Vault-wide. Takes no nodeId, because it stops every payment at every
+            // level rather than muting one agent.
+            return planSetPaused(env.vault, b.paused ?? false);
+        case "allocation":
+            return planSetStrictAllocation(env.vault, b.strict ?? false);
+        case "withdraw":
+            // BASE UNITS, and no default. An amount is the one argument that must
+            // never be guessed: `?? "0"` would be refused by the contract, and any
+            // other fallback would move a quantity nobody asked for.
+            if (!b.amountBase)
+                throw new Error("withdraw needs amountBase, in base units");
+            if (!b.receiverId)
+                throw new Error("withdraw needs receiverId");
+            return planWithdraw(env.vault, b.token ?? env.token, b.amountBase, b.receiverId, env.decimals);
+        case "role":
+            // NOTHING IS DEFAULTED that the user has to confirm. A label, a key
+            // and a funding amount are all things an owner approves in a wallet,
+            // and a guessed one would be approved by someone who never chose it.
+            if (!b.label)
+                throw new Error("role needs a label");
+            if (!b.publicKey)
+                throw new Error("role needs the agent's publicKey");
+            if (!b.fundingYocto)
+                throw new Error("role needs fundingYocto for the gas key");
+            return planAddRole(env.vault, b.label, [
+                {
+                    token: env.token,
+                    dailyCap: b.dailyCap ?? "0",
+                    perTxCap: b.perTxCap ?? "0",
+                    decimals: env.decimals,
+                },
+            ], b.cooldownSec ?? 0, b.recipients ?? null, b.publicKey, b.fundingYocto);
+        case "purge":
+            // `before_day` is read from the contract's own `current_day` by the
+            // caller and passed as current_day + 1 — records are removed strictly
+            // BEFORE it. Defaulting it here would invent a cutoff.
+            if (typeof b.beforeDay !== "number")
+                throw new Error("purge needs beforeDay");
+            return planPurgeSettled(env.vault, b.beforeDay, b.limit ?? 100);
+        default:
+            throw new UnknownActionError(String(b.action));
+    }
+}

package/dist/server.d.ts

@@ -12,8 +12,17 @@
  *   NEAR_VAULT_RPC_URL         default https://test.rpc.fastnear.com
  *   NEAR_VAULT_TOKEN           required (the NEP-141 the vault pays in)
  *   NEAR_VAULT_TOKEN_DECIMALS  default 6
- *   NEAR_VAULT_AGENT_ID        only needed for POST /v1/pay
+ *   NEAR_VAULT_AGENT_ID        only needed for POST /v1/pay. Taken from the key
+ *                              file's `account_id` when one is given.
  *   NEAR_VAULT_AGENT_KEY       only needed for POST /v1/pay (the restricted key)
+ *   NEAR_VAULT_AGENT_KEY_FILE  PREFERRED over the inline value above: a PATH to
+ *                              a ~/.near-credentials-shaped JSON file or a bare
+ *                              key file. See key-file.ts — a path is not a
+ *                              secret, so reading this config to check which
+ *                              vault is wired up stops printing a live private
+ *                              key. If both are set the FILE wins.
+ *   FLOAT_QUOTE_SIGNER_KEY     32-byte hex, for rail=intents
+ *   FLOAT_QUOTE_SIGNER_KEY_FILE  the same, as a path
  *   PORT                       default 8787 (Float's dashboard default)
  */
 export {};