@paybox-sh/sdk 1.0.0 → 2.1.0

package/README.md

@@ -3,7 +3,7 @@
 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`,
+`pay_x402`, `use_service`, `get_portfolio`, `get_buy_link`, `get_deposit_link`,
 `request_account_change`, `get_request`, and the generic plugin discovery,
 contract, and invocation flow. Core operations use the REST API; plugins use
 the same MCP tools as connector hosts, with no hardcoded per-plugin paths.
@@ -21,23 +21,24 @@ 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. Use the CLI on **Muse**, **Grok Bot**, **Grok Computer**, and any agent on a
+routes wallet tasks through existing access or the required setup steps. It
+preserves an explicit wallet choice and resumes the requested task after setup.
+Use the CLI on **Muse**, **Grok Bot**, **Grok Computer**, and any agent on a
 computer with no connector screen — not the grok.com MCP connector path.
 
 ## 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.
-# 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
+# Setup is two commands. `login` authenticates; `connect` pairs a signing key.
+# Pairing prints eight emoji and a link; you open the link and pick that same
+# code in PayBox. The key is generated locally and never leaves this machine,
+# so there is nothing to copy. Neither command needs a browser on the machine
+# running the CLI — approve both from a phone if you like. Add --no-open to
+# either command to print the link without launching a browser.
+paybox login                              # device-code OAuth (browser + passkey)
 paybox login --key pbx_live_…             # personal API key instead (no OAuth)
-PAYBOX_SIGNING_KEY=pbxk1.… paybox login   # supply the signing key non-interactively
+paybox connect                            # pair a signing key
+PAYBOX_SIGNING_KEY=pbxk1.… paybox …       # headless: reuse an already-paired key
 
 paybox credentials                        # list usable credentials
 # `--credential <id>` below is the `credential.id` from that list, not the wallet name.
@@ -57,6 +58,7 @@ paybox buy-link --credential <id> --amount-usd 50   # defaults EVM funding to Ba
 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
+paybox request <request_id> --complete-signature  # sign that parked wallet-sign request locally
 
 # Plugins (enable them in the paybox app first)
 paybox plugins list --status enabled
@@ -79,6 +81,17 @@ its own binary). For project installs use `pnpm up`/`pnpm rm`, or `npx
 `sign`, `swap`, `pay-x402`, and `use-service` can complete in-process with a
 configured `pbxk1.` key. Plugin calls return the raw MCP tool result.
 
+An MCP host can declare its signing surface on each HTTP request with
+`X-Paybox-Signing-Surface: in-process`, `browser`, or `none`. Omit the header to
+keep the existing MCP Apps behavior. The value selects one advisory
+`next_action`; it does not grant signing access. A host must use `in-process`
+only when it has an eligible local callback for that operation. For a parked
+wallet-sign request, call `paybox.completeWalletSignRequest(requestId)` from
+that callback. The SDK reads the stored intent from PayBox and signs the same
+request. It does not create another request. Do not put the signing key in an
+MCP tool argument or model context. `pending_approval` still needs a person;
+`denied` and `error` remain terminal request states.
+
 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
@@ -150,6 +163,37 @@ macOS/Linux). On Windows the POSIX mode bits don't restrict access — the file
 is not access-protected there, so prefer `PAYBOX_API_KEY` / `PAYBOX_SIGNING_KEY`
 env vars on shared Windows machines.
 
+## Headless and CI
+
+Pairing needs a human to confirm the code, so CI cannot pair at run time. Pair
+once ahead of time **as the identity CI will use**, then carry both secrets:
+
+```bash
+# On a laptop. The pbx_live_ key comes from the PayBox app (Agents → create an
+# agent, pick its wallets); it is shown once.
+paybox login --key pbx_live_…      # authenticate as the client CI will use
+paybox connect                     # pick the code; approve on any device
+grep signingKey ~/.config/paybox/config.json
+```
+
+```yaml
+env:
+  PAYBOX_API_KEY: ${{ secrets.PAYBOX_API_KEY }}          # pbx_live_…
+  PAYBOX_SIGNING_KEY: ${{ secrets.PAYBOX_SIGNING_KEY }}  # pbxk1.…
+```
+
+`PayboxClient.fromConfig()` reads both from the environment, so the runner needs
+no config file, no browser, and no TTY.
+
+Those two secrets are a **matched pair**: a signer is bound to the client that
+paired it. Present a `pbxk1.` to a different client — including the throwaway
+client that a plain `paybox login` registers — and signing fails with `agent
+signer belongs to another client`. It reads like a revocation but means you
+paired under a different identity. Rotating the API key mints a new client, so
+re-pair after rotation — `paybox login` drops the stored key when it does this
+and tells you to run `paybox connect`, rather than leaving one that cannot
+sign.
+
 ## Develop
 
 `pnpm-lock.yaml` also contains the `../mcp-app` importer because this SDK