@fluxa-pay/planner 0.1.0 → 0.2.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fluxa-pay/planner",
-  "version": "0.1.0",
-  "description": "FluxA Planner CLI — recommend the right models/APIs/skills for a task, and run paid calls via x402.",
+  "version": "0.2.1",
+  "description": "FluxA Planner CLI. Recommend the right models, APIs and skills for a task, run paid calls via x402, and manage your oneshot APIs.",
   "type": "module",
   "bin": {
     "planner": "planner.mjs"

package/planner.mjs

@@ -301,6 +301,39 @@ async function rawCall(url, method, data, extraHeaders = {}, auth = false) {
   return { status: res.status, text };
 }
 
+// The proxy's API/MCP lanes bill the caller identified by the X-Agent-ID header
+// and reject every non-discovery request without it. Default to the agent_id
+// (UUID) from `fluxa-wallet status`; configs with require_agent_auth need a JWT
+// instead, so agentCall() retries with a freshly minted wallet JWT on the
+// "valid JWT" 401. Both values are cached for the process.
+let _agentId = null;
+async function agentId() {
+  if (_agentId) return _agentId;
+  const s = unwrap(await walletJson(["status"]).catch(() => ({})));
+  const id = s.agent_id || s.agentId || s.id;
+  if (!id) die("could not read agent_id from `fluxa-wallet status` — register once with `fluxa-wallet init`.");
+  return (_agentId = id);
+}
+let _walletJwt = null;
+async function walletJwt() {
+  if (_walletJwt) return _walletJwt;
+  const j = unwrap(await walletJson(["refreshJWT"]).catch(() => ({})));
+  const jwt = j.jwt || j.token;
+  if (!jwt) die("could not mint a wallet JWT (`fluxa-wallet refreshJWT`).");
+  return (_walletJwt = jwt);
+}
+// rawCall + X-Agent-ID, with the UUID→JWT fallback for require_agent_auth configs.
+// Auto-attached headers go FIRST so a caller-supplied `extra` (e.g. a user's
+// `--header "X-Agent-ID: …"`) can override — collisions are surfaced upstream
+// in cmdCall so the override isn't silent.
+async function agentCall(url, method, data, extra = {}) {
+  const r = await rawCall(url, method, data, { "X-Agent-ID": await agentId(), ...extra });
+  if (r.status === 401 && /valid JWT/i.test(r.text)) {
+    return rawCall(url, method, data, { "X-Agent-ID": await walletJwt(), ...extra });
+  }
+  return r;
+}
+
 async function ensureMandate(currency, budget, seconds, url) {
   const cfg = loadConfig();
   // only reuse a signed mandate of the SAME currency with budget left
@@ -339,14 +372,30 @@ function descriptorEndpoints(text) {
 }
 
 async function cmdCall(url, opts = {}) {
-  if (!url || !/^https?:\/\//.test(url)) {
-    return die("usage: planner call <url> [--endpoint <path>] [--data '<json>'] [--pay credits|usdc] [--method GET|POST] [--budget <units>] [--raw]");
+  if (!url) {
+    return die("usage: planner call <url|slug> [--endpoint <path>] [--data '<json>'] [--header 'K: V']… [--pay credits|usdc] [--method GET|POST] [--budget <units>] [--raw]");
   }
+  // accept a bare AgentMarket slug (e.g. `web-search-api`) → the proxy API base.
+  // full http(s) URLs are used as-is.
+  if (!/^https?:\/\//.test(url)) url = `${PROXY}/api/${encodeURIComponent(url)}`;
   const pay = (opts.pay || loadConfig().pay || "credits").toLowerCase();
   const currency = pay === "usdc" ? "USDC" : "FLUXA_MONETIZE_CREDITS";
   const budget = opts.budget ? Number(opts.budget) : (pay === "usdc" ? 5000000 : 500); // ~$5 default
   const seconds = opts.seconds ? Number(opts.seconds) : 28800; // 8h
 
+  // user-supplied request headers (repeatable --header "K: V") are merged
+  // into every outbound call below. A user value wins over the auto-attached
+  // X-Agent-ID; X-Payment is the one exception, see the retry step. We warn
+  // up front when a user header would override an auto-attached one so the
+  // override isn't silent.
+  const userHeaders = opts.headers || {};
+  const reservedNames = ["x-agent-id", "x-payment"];
+  for (const k of Object.keys(userHeaders)) {
+    if (reservedNames.includes(k.toLowerCase())) {
+      console.error(c.dim(`! --header ${k} overrides the auto-attached value`));
+    }
+  }
+
   await ensureAgent();
 
   let targetUrl = url;
@@ -357,7 +406,7 @@ async function cmdCall(url, opts = {}) {
   // real paid sub-endpoints. Resolve it (unless --raw) so the agent doesn't have
   // to read the catalog itself. We never spend without a supplied body.
   if (!opts.raw) {
-    const probe = await rawCall(url, "GET");
+    const probe = await agentCall(url, "GET", undefined, userHeaders);
     const desc = probe.status === 200 ? descriptorEndpoints(probe.text) : null;
     if (desc) {
       const eps = desc.endpoints.filter((e) => e.enabled !== false);
@@ -388,7 +437,7 @@ async function cmdCall(url, opts = {}) {
   }
 
   // call the resolved endpoint — pay if it answers 402
-  let r = await rawCall(targetUrl, method, data);
+  let r = await agentCall(targetUrl, method, data, userHeaders);
   if (r.status !== 402) {
     if (r.status >= 400) die(`${r.status} — ${r.text.slice(0, 300)}`);
     return console.log(r.text); // raw body, no post-processing
@@ -402,8 +451,11 @@ async function cmdCall(url, opts = {}) {
   const xPayment = paid.xPaymentB64 || paid.xPayment;
   if (!xPayment) die("x402-v3 did not return a payment token (xPaymentB64).");
 
-  // 3. retry with the payment token
-  r = await rawCall(url, method, opts.data, { "X-Payment": xPayment });
+  // 3. retry with the payment token (against the resolved endpoint, with
+  // X-Agent-ID + user headers). The freshly-minted X-Payment is appended
+  // LAST so it wins over any user-supplied X-Payment — preserving the x402
+  // settlement that the CLI just signed for this exact 402 challenge.
+  r = await agentCall(targetUrl, method, opts.data, { ...userHeaders, "X-Payment": xPayment });
   if (r.status >= 400) die(`paid retry failed: ${r.status} — ${r.text.slice(0, 300)}`);
   console.log(r.text); // raw body, no post-processing
 }
@@ -446,6 +498,109 @@ async function cmdTopup(vendor, opts = {}) {
   console.log(c.green("✓") + ` topped up ${vendor} · +${added.toLocaleString()} Units · balance ${Number(res.balance ?? 0).toLocaleString()} Units`);
 }
 
+// --- api (manage your oneshot API configs) ----------------------------------
+// `planner api <verb>` — resource-first, like `planner keys`. All verbs auth
+// with auth:true (fxa_live_ key if present, else an auto-minted Agent VC) and
+// are owner-scoped server-side.
+function readSpec(file) {
+  let raw;
+  try {
+    raw = file ? readFileSync(file, "utf8") : readFileSync(0, "utf8");
+  } catch (e) {
+    return die(`could not read spec ${file ? file : "from stdin"}: ${e.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    return die(`spec is not valid JSON${file ? ` (${file})` : " (stdin)"}: ${e.message}`);
+  }
+}
+
+// Overlay --name/--upstream/--wallet/--private/--require-agent-auth onto a spec.
+function applyOverrides(spec, opts) {
+  if (opts.name != null) spec.serverName = opts.name;
+  if (opts.upstream != null) spec.upstreamBaseUrl = opts.upstream;
+  if (opts.wallet != null) spec.yourWallet = opts.wallet;
+  if (opts.private) spec.isPrivate = true;
+  if (opts.requireAgentAuth) spec.requireAgentAuth = true;
+  return spec;
+}
+
+async function cmdApi(sub, rest, opts) {
+  switch (sub) {
+    case "create": case "new": return cmdApiCreate(opts);
+    case "list": case "ls": return cmdApiList();
+    case "get": case "show": return cmdApiGet(rest[0]);
+    case "edit": case "update": return cmdApiEdit(rest[0], opts);
+    default:
+      return die(
+        "usage: planner api <create|list|get|edit>\n" +
+        "  api create --file <spec.json> [--publish] [--dry-run]\n" +
+        "  api list\n" +
+        "  api get <idOrSlug>\n" +
+        "  api edit <idOrSlug> [--file <spec.json>] [--publish] [--dry-run]",
+      );
+  }
+}
+
+async function cmdApiCreate(opts) {
+  const spec = applyOverrides(readSpec(opts.file), opts);
+  spec.status = opts.publish ? "published" : "draft";
+
+  if (opts.dryRun) {
+    console.error(c.dim(`· dry-run — would POST ${spec.status} config to ${PROXY}/configs/api:`));
+    console.log(JSON.stringify(spec, null, 2));
+    return;
+  }
+
+  const { data } = await http(`${PROXY}/configs/api`, { method: "POST", auth: true, body: spec });
+  const tag = data.status === "published" ? c.green("published") : c.dim("draft");
+  console.log(c.green("✓") + ` created ${c.bold(data.slug || data.configId)} · ${tag}`);
+  if (data.proxyUrl) console.log(c.dim(`  proxy: ${data.proxyUrl}`));
+  console.log(c.dim(
+    data.status === "published"
+      ? `  test it:  planner call ${data.proxyUrl || data.slug}`
+      : `  publish:  planner api edit ${data.slug || data.configId} --publish`,
+  ));
+}
+
+async function cmdApiList() {
+  const { data } = await http(`${PROXY}/configs/api`, { auth: true });
+  const rows = data.configs || [];
+  if (!rows.length) return console.log(c.dim("  no api configs yet — `planner api create --file <spec.json>`"));
+  console.log("  " + c.dim(pad("slug", 26) + pad("name", 22) + pad("status", 10) + pad("vis", 9) + pad("eps", 5) + "created"));
+  for (const r of rows) {
+    const st = r.status === "published" ? c.green(pad("published", 10)) : c.dim(pad("draft", 10));
+    const vis = r.isPrivate ? "private" : "public";
+    console.log(`  ${pad(r.slug || r.configId, 26)}${pad(r.serverName || "", 22)}${st}${pad(vis, 9)}${pad(String(r.endpointCount ?? 0), 5)}${(r.createdAt || "").slice(0, 10)}`);
+  }
+}
+
+async function cmdApiGet(idOrSlug) {
+  if (!idOrSlug) return die("usage: planner api get <idOrSlug>");
+  const { data } = await http(`${PROXY}/configs/api/${encodeURIComponent(idOrSlug)}`, { auth: true });
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function cmdApiEdit(idOrSlug, opts) {
+  if (!idOrSlug) return die("usage: planner api edit <idOrSlug> [--file <spec.json>] [--publish] [--dry-run]");
+  const spec = applyOverrides(opts.file ? readSpec(opts.file) : {}, opts);
+  if (opts.publish) spec.status = "published";
+  if (Object.keys(spec).length === 0) {
+    return die("nothing to edit — pass --file and/or flags (--name, --upstream, --publish, …)");
+  }
+
+  if (opts.dryRun) {
+    console.error(c.dim(`· dry-run — would PATCH ${PROXY}/configs/api/${idOrSlug}:`));
+    console.log(JSON.stringify(spec, null, 2));
+    return;
+  }
+
+  const { data } = await http(`${PROXY}/configs/api/${encodeURIComponent(idOrSlug)}`, { method: "PATCH", auth: true, body: spec });
+  const tag = data.status === "published" ? c.green("published") : c.dim("draft");
+  console.log(c.green("✓") + ` updated ${c.bold(data.slug || data.configId)} · ${tag}`);
+}
+
 // --- plan (thin call to server-side endpoint) --------------------------------
 async function cmdPlan(task) {
   if (!task) return die('usage: planner plan "<task>"');
@@ -569,6 +724,13 @@ ${c.bold("Oneshot APIs")}
     ${c.cyan("planner call <base>")}                 show the paid endpoint + its required body
     ${c.cyan("planner call <base> --data '<json>'")} call it; pay the 402 if needed
   ${c.dim("--endpoint <path>")} picks when there are several; ${c.dim("--raw")} hits a URL directly.
+  ${c.bold("Manage your APIs")} ${c.dim("(fxa_live_ key or auto-minted Agent VC)")}
+    ${c.cyan("planner api create --file <spec.json> [--publish]")}   create (draft unless --publish)
+    ${c.cyan("planner api list")}                                    your api configs
+    ${c.cyan("planner api get <idOrSlug>")}                          print the round-trippable spec
+    ${c.cyan("planner api edit <idOrSlug> [--file <s>] [--publish]")} update fields / replace endpoints
+  ${c.dim("Spec JSON: serverName, serverDescription, upstreamBaseUrl, endpoints[]. Wallet defaults from your account.")}
+  ${c.dim("get emits a spec you can edit and feed back: planner api get foo > s.json; planner api edit foo --file s.json")}
 `,
   models: () => `
 ${c.bold("Models — merchant-centric")}
@@ -603,6 +765,7 @@ ${c.bold("Headline")}
   planner plan "<task>"     recommend the models, APIs & skills for a task
   planner call <url>        make a paid API call — handles the x402 mandate + payment
                             [--pay credits|usdc] [--method GET|POST] [--data '<json>']
+                            [--header "Name: Value"]  (repeatable; e.g. an upstream Bearer token)
 
 ${c.bold("Primitives")}  ${c.dim("(all live)")}
   planner search "<q>" [--type api,skill,model]   discover resources
@@ -611,6 +774,8 @@ ${c.bold("Primitives")}  ${c.dim("(all live)")}
   planner topup <vendor> [--credits <N>|--bundle <slug>]   prepay Units (x402, via wallet)
   planner ledger <vendor>                          spend/topup history
   planner keys [create|update <id>|revoke <id>]    manage fxa_live_ API keys (Agent VC only)
+  planner api create --file <spec.json> [--publish]   create a oneshot API (draft by default)
+  planner api list | get <idOrSlug> | edit <idOrSlug>  list / inspect / update your APIs
   planner login <fxa_live_…> / planner whoami      auth
   planner info [units|auth|pay|keys|apis|models|skills] explain how the platform works
 
@@ -627,9 +792,31 @@ function die(msg, ctx) {
 async function main() {
   const args = argv.slice(2);
   const cmd = args[0];
-  const FLAGS = ["--type", "--vendor", "--pay", "--method", "--data", "--budget", "--seconds", "--endpoint", "--credits", "--bundle", "--name", "--cap"];
-  const BOOLS = ["--raw"];
+  const FLAGS = ["--type", "--vendor", "--pay", "--method", "--data", "--budget", "--seconds", "--endpoint", "--credits", "--bundle", "--name", "--cap", "--file", "--upstream", "--wallet", "--header"];
+  const BOOLS = ["--raw", "--publish", "--private", "--require-agent-auth", "--dry-run"];
   const getFlag = (n) => { const i = args.indexOf(n); return i !== -1 ? args[i + 1] : null; };
+  // repeatable flag → array of all values (in order)
+  const getFlagAll = (n) => {
+    const out = [];
+    for (let i = 0; i < args.length - 1; i++) if (args[i] === n) out.push(args[i + 1]);
+    return out;
+  };
+  // parse `--header "Name: Value"` (repeatable) into a headers object. Splits
+  // on the FIRST colon so JWTs/URLs in the value are preserved. Malformed
+  // entries are warned and skipped, never thrown — a broken header shouldn't
+  // poison the whole call.
+  const parseHeaders = (specs) => {
+    const out = {};
+    for (const s of specs) {
+      const i = s.indexOf(":");
+      if (i <= 0) { console.error(c.dim(`! ignoring malformed --header "${s}" (expected "Name: Value")`)); continue; }
+      const name = s.slice(0, i).trim();
+      const value = s.slice(i + 1).trim();
+      if (!name) continue;
+      out[name] = value;
+    }
+    return out;
+  };
   const type = getFlag("--type");
   const vendor = getFlag("--vendor");
   const rest = [];
@@ -647,6 +834,7 @@ async function main() {
         pay: getFlag("--pay"), method: getFlag("--method"), data: getFlag("--data"),
         budget: getFlag("--budget"), seconds: getFlag("--seconds"),
         endpoint: getFlag("--endpoint"), raw: args.includes("--raw"),
+        headers: parseHeaders(getFlagAll("--header")),
       });
     case "search": return cmdSearch(arg, type);
     case "models": return cmdModels(vendor);
@@ -658,6 +846,14 @@ async function main() {
       });
     case "ledger": return cmdLedger(rest[0]);
     case "keys": return cmdKeys(rest[0], rest.slice(1), { name: getFlag("--name"), cap: getFlag("--cap") });
+    case "api":
+      return cmdApi(rest[0], rest.slice(1), {
+        file: getFlag("--file"), name: getFlag("--name"),
+        upstream: getFlag("--upstream"), wallet: getFlag("--wallet"),
+        publish: args.includes("--publish"), private: args.includes("--private"),
+        requireAgentAuth: args.includes("--require-agent-auth"),
+        dryRun: args.includes("--dry-run"),
+      });
     case "login": return cmdLogin(rest[0]);
     case "whoami": return cmdWhoami();
     case "info": return cmdInfo(rest[0]);