@paybox-sh/sdk 0.7.0 → 0.8.1

package/README.md

@@ -1,12 +1,13 @@
 # @paybox-sh/sdk
 
-Typed Node SDK and `paybox` CLI for the Paybox agent API. It mirrors the MCP tool
+Typed Node SDK and `paybox` CLI for the PayBox agent API. It mirrors the MCP tool
 surface — `list_credentials`, `request_payment`, `claim_payment_credentials`,
 `request_wallet_sign`, `request_secret`, `request_swap`, `discover_services`,
 `pay_x402`, `use_service`, `get_portfolio`, `get_buy_link`,
-`request_account_change`, `get_request`, and the plugin tools (`world_*`,
+`request_account_change`, `get_request`, and read-only plugin tools (`world_*`,
 `hyperliquid_*`) — but talks to the REST API directly, with no MCP host and no
 signing iframe.
+Geofenced World money tools are MCP-only.
 
 Wallet signing is **non-custodial and runs in-process**: the SDK reuses the exact
 signing core from the wallet-sign iframe (`@paybox/mcp-app`), builds the chain
@@ -20,18 +21,26 @@ pnpm add @paybox-sh/sdk      # library
 npx @paybox-sh/sdk login     # or use the CLI directly
 ```
 
+Driving this CLI from an agent? [`SKILL.md`](SKILL.md) ships in the package and
+describes the install and login flow as an agent skill: what the human has to do
+(approve wallets, paste one signing key), and what the agent should not do
+around it.
+
 ## CLI
 
 ```bash
 # Authenticate: OAuth in the browser (approve with a passkey), or store a key.
 # `paybox login` is a guided two-step: OAuth, then it opens the app to provision
 # a wallet signing key and prompts you to paste the `pbxk1.` token back.
-paybox login                              # OAuth 2.1 + PKCE, then provision a key
+# The OAuth step is a device-code grant, so the browser that approves does not
+# have to be on the machine running the CLI.
+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)
@@ -44,13 +53,13 @@ paybox discover --raw "weather api"       # debug: uncurated compact summaries
 paybox pay-x402 --credential <id> --url https://svc/api --accepts @accepts.json
 paybox use-service --credential <id> --url https://svc/api   # paybox pays + fetches
 paybox claim <request_id>                 # claim an approved payment's card (one-time)
-paybox buy-link --credential <id> --amount-usd 50   # MoonPay on-ramp URL for a wallet
+paybox buy-link --credential <id> --amount-usd 50   # defaults EVM funding to Base
+paybox buy-link --credential <id> --destination eip155:1 --currency eth
 paybox account-change --note "need a wallet grant"  # manage_url for the user to open
 paybox request <request_id> --wait        # poll a pending request
 
 # Plugins (enable them in the paybox app first)
 paybox world markets --status active      # browse prediction markets
-paybox world buy --credential <id> --mint <outcome-mint> --size 10 --wait
 paybox hyperliquid markets                # spot discovery
 
 paybox version                            # installed version (+ update check)
@@ -66,13 +75,8 @@ clears `~/.config/paybox` and prints the `npm rm -g` line (a package can't remov
 its own binary). For project installs use `pnpm up`/`pnpm rm`, or `npx
 @paybox-sh/sdk@latest` to always run the latest without installing.
 
-`sign`, `swap`, `pay-x402`, `use-service`, and the `world` trade commands
-complete in-process when a `pbxk1.` signing key is configured and the operation
-clears immediately (autonomous grant). When the grant requires approval — World
-trades always do — pass `--wait`: the CLI waits for your passkey approval in the
-app and then signs in-process (there is no signing window on this surface).
-Without `--wait` the command returns `pending_approval`; approve in the app,
-then re-run or poll `paybox request <id>`.
+`sign`, `swap`, `pay-x402`, and `use-service` can complete in-process with a
+configured `pbxk1.` key. World buy/sell/redeem are MCP-only.
 
 For a Solana `swap` the SDK re-pins a fresh recent blockhash immediately before
 signing (parity with the signing window — the quote-time blockhash expires
@@ -93,14 +97,18 @@ import { PayboxClient } from "@paybox-sh/sdk";
 const paybox = PayboxClient.fromConfig();          // reads ~/.config/paybox + env
 // or: new PayboxClient({ apiKey: "pbx_live_…", signingKey: "pbxk1.…" });
 
-const creds = await paybox.listCredentials();
+const { credentials, ungranted } = await paybox.listCredentials();
 const pay = await paybox.requestPayment({
-  credentialId: creds[0].credential.id,
+  credentialId: credentials[0].credential.id,
   merchant: "Acme",
   merchantUrl: "https://acme.com",
   amountCents: 1999,
 });
 
+// Ungranted credentials the user owns but hasn't granted this connector — pass
+// an id to request_account_change's `add` to ask for access.
+console.log(ungranted.map((c) => `${c.name} (${c.kind})`));
+
 const sig = await paybox.requestWalletSign({
   credentialId: walletId,
   chain: "eip155:8453",
@@ -134,6 +142,10 @@ env vars on shared Windows machines.
 
 ## Develop
 
+`pnpm-lock.yaml` also contains the `../mcp-app` importer because this SDK
+consumes the iframe's signing core through `file:../mcp-app`. The iframe build
+shares this dependency resolution but keeps its installed modules separate.
+
 ```bash
 pnpm install
 pnpm typecheck

package/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: PayBox CLI setup
+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
+  when the user says "install PayBox", "set up PayBox", "instalar PayBox", or
+  asks an agent to connect their PayBox wallet.
+---
+
+# PayBox CLI setup
+
+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.
+
+## Install
+
+```bash
+npm install -g @paybox-sh/sdk
+```
+
+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.
+
+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.
+
+## Log in
+
+Run this once, in the same turn the user asks:
+
+```bash
+paybox login
+```
+
+Add `--base-url` and `--app-url` for an environment other than the default.
+
+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,
+then opens the signing-key page and prompts for the key.
+
+Login writes progress to stderr as plain prose, not JSON. Watch for the
+verification URL and the `Code:` line.
+
+### Step 1 — Authorize wallets
+
+The moment login prints the verification URL and code, put **one** message in
+front of the user: a markdown link labeled **Authorize wallets** pointing at that
+URL, plus the code.
+
+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. 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.
+If the code expires before they approve, run `paybox login` again for a fresh
+one rather than reusing the old link.
+
+### Step 2 — Paste the signing key
+
+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, 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.
+
+Wallet signing is non-custodial: the key stays on the user's machine and PayBox
+never holds it. Never print, log, or echo it.
+
+### Step 3 — Confirm
+
+```bash
+paybox --json whoami
+```
+
+`canSign` must be `true`. If it is `false` the key did not save; redo step 2
+rather than continuing, because signing and swaps will fail without it.
+
+## What the user sees
+
+From the install request until `canSign` is `true`, exactly two messages, in
+this order:
+
+1. The **Authorize wallets** link plus the code.
+2. The masked `pbxk1.` field, after the signing-key page has opened.
+
+Nothing else. No "Installing…", "Opening…", "Got it", no CLI version, package
+manager, config path, or request id, and no narration of a retry or fallback. If
+something is blocked, switch approaches quietly. If you have nothing they need
+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. 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.
+
+## A setup that went wrong
+
+- The user had to prompt you after approving wallet access.
+- The key field appeared before the signing-key page opened.
+- You asked the user to click the signing-key link, or to type `done`.
+- You opened either page twice.
+- Setup chat contained anything besides those two messages.
+- A token, API key, or `pbxk1.` value reached the transcript.