@paybox-sh/sdk 0.5.0 → 0.8.0

package/README.md

@@ -1,10 +1,13 @@
 # @paybox-sh/sdk
 
-Typed Node SDK and `paybox` CLI for the Paybox agent API. It mirrors the MCP tool
-surface — `list_credentials`, `request_payment`, `request_wallet_sign`,
-`request_secret`, `request_swap`, `discover_services`, `pay_x402`, `use_service`,
-`get_portfolio`, `get_request` — but talks to the REST API directly, with no MCP
-host and no signing iframe.
+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 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
@@ -18,13 +21,20 @@ 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
@@ -37,11 +47,20 @@ paybox sign --credential <id> --intent '{"op":"message","message":"gm"}'
 paybox swap --credential <id> --src-chain eip155:8453 \
   --src-token native --dst-token 0x… --amount 1000000000000000
 paybox portfolio --address 0x… --networks 1,8453
-paybox discover "weather api"             # browse paid x402 services (Bazaar)
+paybox discover "weather api"             # browse curated paid x402 services
+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   # 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 hyperliquid markets                # spot discovery
+
 paybox version                            # installed version (+ update check)
 paybox update                             # update the global install to latest
 paybox uninstall                          # clear stored config (prints npm rm)
@@ -55,16 +74,19 @@ 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`, and `use-service` complete in-process when a `pbxk1.`
-signing key is configured and the operation clears immediately (autonomous
-grant). When the grant requires approval, the command returns `pending_approval`;
-approve in the app, then `paybox request <id> --wait`.
+`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
+within ~60–90s, often before signing), so a swap that dwells for approval no
+longer broadcasts as `BlockhashNotFound`. EVM swaps are unaffected.
 
 `pay-x402` is header mode — on success `output.value.x_payment` is the `X-PAYMENT`
 header to replay on the original request. `use-service` is gateway mode — paybox
 makes the paid call for you and returns the resource's reply on
-`output.value.response`. Pass `--accepts` from the resource's own 402 (browse the
-catalog with `paybox discover`).
+`output.value.response`. Pass `--accepts` from the resource's own 402 (start from
+the curated Bazaar set with `paybox discover`).
 
 ## Library
 
@@ -74,14 +96,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",
@@ -91,6 +117,7 @@ const sig = await paybox.requestWalletSign({
 // x402: discover a paid endpoint, then pay it — header mode (you replay the
 // X-PAYMENT header) or gateway mode (paybox fetches the paid content for you).
 const services = await paybox.discoverServices("weather api");
+const rawServices = await paybox.discoverServices("weather api", { raw: true }); // debug only
 const paid = await paybox.useService({ credentialId: walletId, url: services[0].resource });
 // paid.response.output.value.response holds the resource's reply
 ```
@@ -114,6 +141,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,118 @@
+---
+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. They should not open the link in a native
+PayBox mobile app; that path cannot complete a device-code approval.
+
+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, 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.
+
+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. 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.