@paybox-sh/sdk 0.8.0 → 0.8.2

package/README.md

@@ -37,9 +37,10 @@ around it.
 paybox login                              # device-code OAuth, then provision a key
 paybox login --no-provision               # OAuth only, skip the key step
 paybox login --key pbx_live_…             # personal API key instead (no OAuth)
-paybox login --signing-key pbxk1.…        # supply the signing key non-interactively
+PAYBOX_SIGNING_KEY=pbxk1.… paybox login   # supply the signing key non-interactively
 
 paybox credentials                        # list usable credentials
+# `--credential <id>` below is the `credential.id` from that list, not the wallet name.
 paybox pay --credential <id> --merchant Acme --url https://acme.com --amount 1999
 paybox secret --credential <id> --purpose "deploy"        # one-time token
 paybox secret --credential <id> --raw                     # raw value (grant-gated)

package/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: PayBox CLI setup
+version: 0.8.3
 description: >-
   Install and log in to the PayBox CLI (@paybox-sh/sdk) so an agent can pay,
   sign, and hold wallet, card, and secret credentials on the user's behalf. Use
@@ -9,6 +10,10 @@ description: >-
 
 # PayBox CLI setup
 
+The human and agent guide is `https://docs.paybox.sh` (start at
+getting-started and connect/mcp). This file is only the CLI film. Grok
+(grok.com) and Grok Bots are different hosts; do not treat one as the other.
+
 The user asks to install PayBox. Two things need them: they approve wallet
 access with a passkey, and they paste one signing key. Everything else is yours,
 and they should not see it happen.
@@ -19,6 +24,13 @@ and they should not see it happen.
 npm install -g @paybox-sh/sdk
 ```
 
+Then confirm what you got: `paybox --json version` reports the version and
+`binary`, the path that answered. Two things go wrong here and both are quiet.
+If the command is not found, the global prefix is not on this shell's `PATH`;
+`npm prefix -g` gives you that prefix, and the binary sits in its `bin`. If
+`binary` is under a different prefix, an older `paybox` sits earlier on `PATH`
+and will keep answering every command you run.
+
 The CLI runs wherever you run it, which is often not the user's own machine.
 That is fine: login uses an OAuth device-code grant, so the browser that
 approves does not have to be the one the CLI can reach.
@@ -27,6 +39,10 @@ Never delete or overwrite an existing config directory. To isolate a run from
 credentials the user already has, point `PAYBOX_CONFIG_DIR` at a fresh
 directory.
 
+Give each parallel run its own directory too. Commands sharing one config race
+each other's token refresh, and the loser fails with `refresh token has already
+been used`. Retry that one command once; do not run `login` again.
+
 ## Log in
 
 Run this once, in the same turn the user asks:
@@ -37,6 +53,11 @@ paybox login
 
 Add `--base-url` and `--app-url` for an environment other than the default.
 
+If a config directory already exists, check `paybox --json whoami` first. When
+`canSign` is already `true`, setup is done: do not run `login`, and do not send
+the authorize link or the key field again. A second authorize link in one chat
+reads as a setup that failed.
+
 The command drives the whole flow itself. Do not reimplement any of it: it
 registers a client, starts device authorization, prints a verification URL and a
 short user code, tries to open that URL locally, polls until the user approves,
@@ -55,8 +76,8 @@ Send that link even though the CLI also tries to open a browser. When the CLI
 is not on the user's machine, that local open is useless or invisible, and your
 message is the only way they reach the page.
 
-The user approves in the browser. They should not open the link in a native
-PayBox mobile app; that path cannot complete a device-code approval.
+The user approves in the browser. If the link opens the PayBox mobile app and
+errors instead, have them open it in a browser.
 
 Then wait. The poll is the continue signal. Do not ask the user to type `done`,
 confirm, or send a screenshot, and do not end your turn while login is running.
@@ -69,9 +90,10 @@ After approval, login opens the signing-key page and prompts for the key.
 Present a **masked input** for the `pbxk1.` value and write what the user gives
 you to that prompt's stdin.
 
-Pass it through the prompt, never as `login --signing-key <value>` on the
-command line: an argument lands in shell history and is visible to anyone who
-can list processes.
+Pass it through the prompt, or set `PAYBOX_SIGNING_KEY` before running `login`
+when nothing is attached to stdin. Never pass it as `login --signing-key <value>`
+on the command line: an argument lands in shell history and is visible to anyone
+who can list processes.
 
 Do not ask the user to click the signing-key link, it is already open. Do not
 show the key field before that page has opened, and do not open it twice.
@@ -103,10 +125,52 @@ to act on, send nothing.
 
 Match the user's language. Default to English unless they write otherwise.
 
-Once `canSign` is `true`, show them what they now have: `paybox --json
-credentials` for the granted wallets, then `paybox --json portfolio --address
-<wallet>` for balances. Render a compact table, never addresses or raw JSON. The
-CLI cannot create wallets; it uses what the user granted during authorization.
+## Once setup is done
+
+The silence rules above are about setup, and end here.
+
+Show them what they now have: `paybox --json credentials` for the granted
+wallets, then `paybox --json portfolio --address <wallet>` for balances. Every
+`--credential` takes the `credential.id` from that list; a wallet's name is not
+an id and the command will refuse it. Render a compact table, never addresses or
+raw JSON. The CLI cannot create wallets; it uses what the user granted during
+authorization.
+
+When you run several operations at once, report each one where the user is
+watching, as it lands, with its request id. Each spends real money on its own,
+and one combined summary at the end leaves nobody able to tell which transaction
+came from which request.
+
+After that table, do two things with plugins. Do not treat Welcome as a
+catalog index. There may be tens or thousands.
+
+1. Send them to enable plugins on the web: a markdown link labeled
+   **Plugins** to `https://app.paybox.sh/plugins`. That is the PayBox
+   app, not a host Settings → Plugins screen. Ask them to turn on what
+   they want to use, then say when they are back.
+
+2. Then call `discover_plugins` with `status` `enabled`, no `query`, and
+   a small `limit`. That page is what they have on, not the store. From
+   those plugins plus the portfolio, suggest a few concrete next moves
+   (about six, not one row per plugin). Use each result's `name` and
+   contract. Be specific: amounts, which wallet UUID, which market or
+   vault from the contract. Mix two enabled plugins in one suggestion
+   when that serves the same goal (for example fund or swap, then put
+   the result to work). If nothing is enabled, skip the suggestion list
+   and stay on the Plugins link.
+
+When they name a plugin or a job, search: `discover_plugins` with `query`
+set to what they asked, `status` `enabled` if they already turned it on,
+then page with `next_cursor` only while the current page has no match.
+Official plugin money uses MCP: `get_contract` with `contract_uri`
+unchanged → `use_plugin` with that contract's `plugin_id`, `tool_id`,
+and `input`. Do not invent a `paybox <plugin>` command; only use CLI
+groups that `paybox --help` already lists. Enabled plugin tools may also
+appear on `tools/list`. Plugin money always pauses for passkey.
+
+If prod MCP (`https://api.paybox.sh/mcp`) is `unreachable` or `needsAuth` while
+`paybox --json whoami` still works, say that. Do not send the human to Settings.
+Do not switch to staging. Do not report the dollar as sent.
 
 ## A setup that went wrong
 

package/dist/{chunk-7VW4QMV4.js → chunk-WRPYONXW.js}

@@ -146,8 +146,6 @@ async function loginDevice(baseUrl, opts = {}) {
       token_endpoint_auth_method: "none",
       grant_types: ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"],
       response_types: ["code"],
-      // Must match (or be a superset of) what we ask for below — the server
-      // only grants scope that was declared at registration.
       scope
     })
   });
@@ -392,6 +390,22 @@ function buildX402Envelope(typedData, binding, creds) {
   );
   return { api_pub: creds.apiPubHex, signed_body, agent_signature };
 }
+function buildX402SolanaEnvelope(transactionBase64, binding, creds) {
+  if (!binding.walletId) {
+    throw new Error("PayBox did not supply a wallet id for this payment.");
+  }
+  if (!binding.keyId || !binding.derivationPath) {
+    throw new Error(
+      "This wallet isn't provisioned for signing yet (missing key binding). Re-provision it in the PayBox app, then retry."
+    );
+  }
+  const { signed_body, agent_signature } = buildEnvelope(
+    solanaSigningPayload(transactionBase64),
+    binding,
+    creds
+  );
+  return { api_pub: creds.apiPubHex, signed_body, agent_signature };
+}
 function buildIssuedAtEnvelope(creds) {
   const signedBodyBytes = new TextEncoder().encode(
     JSON.stringify({ issued_at: (/* @__PURE__ */ new Date()).toISOString() })
@@ -538,19 +552,33 @@ function isSolanaRefreshablePlan(plan) {
     (t) => t.kind === "swap" || t.kind === "prediction_trade" || t.kind === "jupiter_swap"
   );
 }
-async function refreshSwapPlan(post, requestId, plan) {
+async function refreshPlan(post, requestId) {
   const r = await post(`/agent/requests/${requestId}/refresh`, {});
   if (!r || typeof r.plan !== "object" || r.plan === null) {
-    throw new Error("swap refresh returned no plan");
+    throw new Error("refresh returned no plan");
   }
-  const refreshed = r.plan;
+  return r.plan;
+}
+async function refreshSwapPlan(post, requestId) {
+  const refreshed = await refreshPlan(post, requestId);
   if (!Array.isArray(refreshed.txs) || refreshed.txs.length === 0) {
     throw new Error("swap refresh returned a plan with no txs");
   }
   return refreshed;
 }
+function isSolanaRailX402(plan) {
+  return plan.x402?.rail === "solana";
+}
+async function refreshX402SolanaTx(post, requestId) {
+  const refreshed = await refreshPlan(post, requestId);
+  const tx = refreshed.solana?.transaction;
+  if (typeof tx !== "string" || tx.length === 0) {
+    throw new Error("x402 refresh returned a plan with no Solana transaction");
+  }
+  return tx;
+}
 async function signSwapRequest(post, requestId, plan, creds) {
-  const signPlan = isSolanaRefreshablePlan(plan) ? await refreshSwapPlan(post, requestId, plan) : plan;
+  const signPlan = isSolanaRefreshablePlan(plan) ? await refreshSwapPlan(post, requestId) : plan;
   let binding = {
     walletId: signPlan.binding.wallet_id,
     keyId: signPlan.binding.key_id ?? "",
@@ -571,7 +599,7 @@ async function signX402Request(post, requestId, plan, creds) {
   if (binding.walletId && (!binding.keyId || !binding.derivationPath)) {
     binding = await resolveBinding(post, requestId, creds);
   }
-  const envelope = buildX402Envelope(
+  const envelope = isSolanaRailX402(plan) ? buildX402SolanaEnvelope(await refreshX402SolanaTx(post, requestId), binding, creds) : buildX402Envelope(
     plan.typed_data,
     binding,
     creds
@@ -586,6 +614,9 @@ function signingResultForResponse(result, response) {
   const exposesPlan = response.status === "pending_approval" || response.status === "pending_signature";
   return { ...result, response, plan: exposesPlan ? result.plan : null };
 }
+function didNotHappen(r) {
+  return r?.status === "denied" || r?.status === "error";
+}
 var PayboxError = class extends Error {
   constructor(status, body, context) {
     super(`paybox ${context} failed (${status}): ${body}`);
@@ -605,7 +636,6 @@ var PayboxClient = class _PayboxClient {
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.fetchImpl = options.fetchImpl ?? fetch;
   }
-  /** Build a client from `~/.config/paybox/config.json` + env, with overrides. */
   static fromConfig(overrides = {}) {
     const cfg = loadConfig();
     const client = new _PayboxClient({
@@ -629,7 +659,6 @@ var PayboxClient = class _PayboxClient {
       return null;
     }
   }
-  /** Whether in-process signing is available (a parseable `pbxk1.` key is set). */
   get canSign() {
     return this.signingCreds() !== null;
   }
@@ -668,19 +697,14 @@ var PayboxClient = class _PayboxClient {
     return text ? JSON.parse(text) : void 0;
   }
   poster = (path, body) => this.request("POST", path, { body });
-  /** List granted credentials plus the `ungranted` credentials (id, name, kind,
-   *  safe metadata) the user owns but hasn't granted this connector. */
   listCredentials() {
     return this.request("GET", "/agent/grants");
   }
-  /** Token balances across chains (the `get_portfolio` tool). */
   getPortfolio(args) {
     return this.request("GET", "/agent/portfolio", {
       query: { address: args.address, network_ids: args.networkIds }
     });
   }
-  /** Verify one confirmed Solana transaction's exact wallet/mint effect, then
-   *  read the current balance at or after its slot (`verify_solana_balance`). */
   verifySolanaBalance(args) {
     const body = {
       address: args.address,
@@ -689,7 +713,6 @@ var PayboxClient = class _PayboxClient {
     };
     return this.request("POST", "/agent/portfolio/verify-solana-balance", { body });
   }
-  /** Charge a card credential (the `request_payment` tool). */
   requestPayment(args) {
     const operation = {
       type: "payment",
@@ -701,7 +724,6 @@ var PayboxClient = class _PayboxClient {
     };
     return this.request("POST", "/agent/request", { body: { operation } });
   }
-  /** Reveal a secret credential (the `request_secret` tool). */
   requestSecret(args) {
     const operation = {
       type: "secret",
@@ -711,12 +733,6 @@ var PayboxClient = class _PayboxClient {
     };
     return this.request("POST", "/agent/request", { body: { operation } });
   }
-  /** Sign with a wallet credential (the `request_wallet_sign` tool). Signs
-   *  in-process and returns the completed request when a signing key is set and
-   *  the request clears immediately; otherwise returns the pending response.
-   *  Uses `/agent/wallet-sign`, which echoes the wallet binding only while
-   *  approval or signature is pending so the signer need not resolve it
-   *  separately. Terminal responses carry a null binding. */
   async requestWalletSign(args, opts = {}) {
     return this.withExpiryRetry(
       async () => {
@@ -741,10 +757,6 @@ var PayboxClient = class _PayboxClient {
       (r) => r
     );
   }
-  /** Swap tokens from a wallet credential (the `request_swap` tool). Returns the
-   *  parked response and its sign-ready plan while approval or signature is
-   *  pending; terminal responses carry a null plan. Signs + submits in-process
-   *  when a signing key is set and the swap cleared immediately. */
   async requestSwap(args, opts = {}) {
     return this.withExpiryRetry(
       async () => {
@@ -757,7 +769,6 @@ var PayboxClient = class _PayboxClient {
           dst_token: args.dstToken,
           amount: args.amount,
           swap_direction: args.swapDirection ?? "exact-amount-in",
-          // Keep in sync with the request_swap MCP tool default (server side).
           slippage_bps: args.slippageBps ?? 150,
           recipient: args.recipient ?? null,
           value_cents: args.valueCents ?? null
@@ -770,10 +781,6 @@ var PayboxClient = class _PayboxClient {
       (r) => r.response
     );
   }
-  /** Complete a swap request: optionally wait out a `pending_approval` dwell,
-   *  then sign the plan in-process and submit envelopes. Signing first refreshes
-   *  the parked request via `/agent/requests/{id}/refresh`, so a long approval
-   *  dwell never signs stale bytes. */
   async completeSwap(result, opts) {
     const creds = this.signingCreds();
     if (!(opts.autoSign ?? true) || !creds) {
@@ -797,8 +804,6 @@ var PayboxClient = class _PayboxClient {
       await this.requestAfterSign(response.request_id, opts.waitForApproval)
     );
   }
-  /** Poll while the request sits in `pending_approval` (the user is approving
-   *  with their passkey); returns the first non-approval state. */
   async waitWhileApproval(requestId, wait) {
     const o = typeof wait === "object" ? wait : {};
     const interval = o.intervalMs ?? 2e3;
@@ -809,25 +814,14 @@ var PayboxClient = class _PayboxClient {
       await new Promise((res) => setTimeout(res, interval));
     }
   }
-  /** Run an operation and, if it terminates on a server-marked expiry
-   *  (`retryable` on a terminal `error`/`denied`: the window elapsed and nothing
-   *  was signed or spent), re-issue it exactly once (SPE-456). Never loops: the
-   *  second attempt's result is returned as-is. */
   async withExpiryRetry(run, responseOf) {
     const first = await run();
     const r = responseOf(first);
-    if ((r.status === "error" || r.status === "denied") && r.retryable) {
+    if (didNotHappen(r) && r.retryable) {
       return run();
     }
     return first;
   }
-  /** Sign a parked request; if the sign/submit call fails, reconcile against the
-   *  authoritative state once (SPE-456). The server leaves a pre-broadcast
-   *  completion failure recoverable — the claim is released and the row stays
-   *  `pending_signature` — so re-sign a still-open request a single time; a
-   *  terminal or already-broadcast row is left as-is for the caller to read (and
-   *  for `withExpiryRetry` to re-issue if it is retryable). Bounded to one extra
-   *  attempt: a second failure propagates. */
   async signWithReconcile(requestId, sign) {
     try {
       await sign();
@@ -837,7 +831,6 @@ var PayboxClient = class _PayboxClient {
       await sign();
     }
   }
-  /** Discover x402 services with the original array-returning response. */
   async discoverServices(query, opts = {}) {
     const result = await this.request("GET", "/agent/services", {
       query: {
@@ -848,8 +841,6 @@ var PayboxClient = class _PayboxClient {
     });
     return result.services;
   }
-  /** Discover one bounded page of x402 services. Reuse the returned cursor with
-   * the same query and network while `has_more` is true. */
   async discoverServicesPage(query, opts = {}) {
     return this.request("GET", "/agent/services", {
       query: {
@@ -861,10 +852,6 @@ var PayboxClient = class _PayboxClient {
       }
     });
   }
-  /** Pay a paid x402 endpoint from a wallet credential (the `pay_x402` tool,
-   *  header mode). Signs in-process when a signing key is set and the payment
-   *  clears immediately — then the X-PAYMENT header is on the completed
-   *  response's `output.value.x_payment` (replay it on the original request). */
   async payX402(args, opts = {}) {
     return this.withExpiryRetry(
       async () => {
@@ -880,9 +867,6 @@ var PayboxClient = class _PayboxClient {
       (r) => r.response
     );
   }
-  /** Fetch a paid x402 resource and have paybox pay for it (the `use_service`
-   *  tool, gateway mode): paybox probes the url, pays the 402, re-fetches with the
-   *  payment, and returns the resource's reply on `output.value.response`. */
   async useService(args, opts = {}) {
     return this.withExpiryRetry(
       async () => {
@@ -899,9 +883,6 @@ var PayboxClient = class _PayboxClient {
       (r) => r.response
     );
   }
-  /** Shared completion for the two x402 entry points: optionally wait out a
-   *  `pending_approval` dwell, then sign the parked typed data in-process and
-   *  return the finished request, exactly like the swap path. */
   async completeX402(result, opts) {
     const creds = this.signingCreds();
     if (!(opts.autoSign ?? true) || !creds) {
@@ -925,20 +906,12 @@ var PayboxClient = class _PayboxClient {
       await this.requestAfterSign(response.request_id, opts.waitForApproval)
     );
   }
-  /** Claim the usable card credentials of an approved payment (the
-   *  `claim_payment_credentials` tool). One-time: the claim is consumed. */
   claimPaymentCredentials(requestId) {
     return this.request("POST", `/agent/requests/${requestId}/credentials`);
   }
-  /** Open the account-change flow (the `request_account_change` tool): returns a
-   *  `manage_url` deep link for the USER to open — they update this client's
-   *  access (or add a credential) in their own passkey-gated app session.
-   *  Nothing is parked or applied server-side. */
   requestAccountChange(note) {
     return this.request("POST", "/agent/account-change", { body: { note } });
   }
-  /** A signed MoonPay checkout URL funding a granted wallet (the `get_buy_link`
-   *  tool). Share the URL with the user; generating it charges nothing. */
   getBuyLink(args) {
     return this.request("GET", "/agent/buy-link", {
       query: {
@@ -949,8 +922,6 @@ var PayboxClient = class _PayboxClient {
       }
     });
   }
-  // ---- World REST discovery; money tools require the geofenced MCP window. ----
-  /** Browse World prediction markets (the `world_find_markets` tool). */
   worldMarkets(args = {}) {
     return this.request("GET", "/agent/world/markets", {
       query: {
@@ -963,25 +934,19 @@ var PayboxClient = class _PayboxClient {
       }
     });
   }
-  /** One World event with its markets (the `world_get_market` tool). Nested
-   *  markets default on, matching the tool — they carry the outcome mint ids
-   *  the orderbook/trade calls need. */
   worldMarket(eventTicker, withNestedMarkets = true) {
     return this.request("GET", "/agent/world/market", {
       query: {
         event_ticker: eventTicker,
-        // Omit when true (the server default); send only the explicit opt-out.
         with_nested_markets: withNestedMarkets ? void 0 : "false"
       }
     });
   }
-  /** A World market's orderbook (the `world_orderbook` tool). */
   worldOrderbook(id, byMint = false) {
     return this.request("GET", "/agent/world/orderbook", {
       query: { id, by_mint: byMint ? "true" : void 0 }
     });
   }
-  /** A World market's price history (the `world_market_prices` tool). */
   worldPrices(args) {
     return this.request("GET", "/agent/world/prices", {
       query: {
@@ -992,45 +957,30 @@ var PayboxClient = class _PayboxClient {
       }
     });
   }
-  /** Filter addresses down to World outcome mints (the
-   *  `world_filter_outcome_mints` tool). */
   worldFilterOutcomeMints(addresses) {
     return this.request("POST", "/agent/world/filter-outcome-mints", {
       body: { addresses }
     });
   }
-  /** A wallet's World prediction-market positions: classified `positions` /
-   *  `settled` entries (each with a `position_result`) plus `settlement_cash`
-   *  for a settled winner's CASH cash-out (swap CASH to USDC via request_swap).
-   *  The `world_positions` tool. */
   worldPositions(address) {
     return this.request("GET", "/agent/world/positions", { query: { address } });
   }
-  // ---- Hyperliquid plugin (read-only spot discovery) — requires the user to
-  // have enabled the `hyperliquid` plugin in the paybox app. ----
-  /** Hyperliquid spot markets (the `hyperliquid_markets` tool). */
   hyperliquidMarkets() {
     return this.request("GET", "/agent/hyperliquid/markets");
   }
-  /** Hyperliquid spot prices (the `hyperliquid_prices` tool). */
   hyperliquidPrices() {
     return this.request("GET", "/agent/hyperliquid/prices");
   }
-  /** Resolve one Hyperliquid token by name (the `hyperliquid_token` tool). */
   hyperliquidToken(name) {
     return this.request("GET", "/agent/hyperliquid/token", { query: { name } });
   }
-  /** Poll a request's status (the `get_request` tool). */
   getRequest(requestId) {
     return this.request("GET", `/agent/requests/${requestId}`);
   }
-  /** After in-process sign, `--wait` polls through settlement/confirmation;
-   *  without it, return the first snapshot (the historical no-wait contract). */
   requestAfterSign(requestId, wait) {
     if (!wait) return this.getRequest(requestId);
     return this.waitForRequest(requestId, typeof wait === "object" ? wait : {});
   }
-  /** Poll until the request leaves a pending state (or the timeout elapses). */
   async waitForRequest(requestId, opts = {}) {
     const interval = opts.intervalMs ?? 2e3;
     const deadline = Date.now() + (opts.timeoutMs ?? 3e5);
@@ -1056,7 +1006,8 @@ export {
   loadConfig,
   saveConfig,
   credsFromToken,
+  didNotHappen,
   PayboxError,
   PayboxClient
 };
-//# sourceMappingURL=chunk-7VW4QMV4.js.map
+//# sourceMappingURL=chunk-WRPYONXW.js.map