@paybox-sh/sdk 2.0.0 → 2.2.0

package/README.md

@@ -21,9 +21,9 @@ 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, confirm one code), 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
@@ -33,7 +33,8 @@ computer with no connector screen — not the grok.com MCP connector path.
 # 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.
+# 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 connect                            # pair a signing key
@@ -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
@@ -133,6 +146,64 @@ const result = await paybox.usePlugin({
 });
 ```
 
+## Run and resume a plugin request
+
+`runPlugin` invokes a plugin once and drives its stored request. `resumeRequest`
+reads an existing request and does not invoke the plugin again. Signing follows
+validated Solana/EVM transaction capabilities and server-owned `refresh_before_sign`,
+not plugin names. `resumeRequest` also consumes stored `wallet_sign` transaction
+intents through the existing signer. Unknown formats, versioned plans and gasless
+prepared plans stop with `outcome: "unsupported"`. Public plugins also use
+`use_plugin`, with their installation ID as `plugin_id`; request completion does
+not by itself prove a purchase or broadcast. Use the plugin contract to select an
+enabled tool and construct its input.
+
+```ts
+import type { UsePluginArgs } from "@paybox-sh/sdk";
+
+async function runApprovedOperation(operation: UsePluginArgs) {
+  const execution = await paybox.runPlugin(operation, { timeoutMs: 60_000 });
+  if (execution.requestId) {
+    await saveRequestId(execution.requestId);
+  }
+  return execution;
+}
+
+const execution = await paybox.resumeRequest(savedRequestId, {
+  waitForApproval: true,
+  timeoutMs: 60_000,
+});
+```
+
+The example assumes application-owned storage through `saveRequestId` and
+`savedRequestId`. Keep the request ID so another process can resume after a pause.
+A paired signing key enables automatic signing. Set `autoSign: false` to stop
+before signing. The server still enforces wallet grants and approval requirements.
+
+| Outcome | Meaning |
+| --- | --- |
+| `terminal` | Check `response.status`: `success`, `denied`, or `error`. A signature alone is not success. |
+| `approval_required` | The user must approve through Paybox. Approval waiting is disabled by default. |
+| `signing_required` | Automatic signing is disabled or a signing key is unavailable. |
+| `unsupported` | The result or signing plan is outside the supported contract. |
+| `reconcile_required` | The client cannot confirm completion. Query the same request before further action. |
+| `deadline_exceeded` / `cancelled` | The client stopped. The server operation can still finish. |
+
+The default deadline is 300 seconds and includes network calls. Polling starts at
+2 seconds, doubles when the status is unchanged, and stops increasing at 30 seconds.
+A status change resets the interval. `intervalMs` sets the starting interval from
+1 to 30,000 milliseconds. `signal` accepts an `AbortSignal` for cancellation.
+
+Do not start concurrent drivers for the same request. After an uncertain result,
+use `getRequest` before an explicit resume. The driver does not automatically retry
+a signature submission or create a replacement request. If invocation stops before
+a request ID arrives, reconcile outside this driver before invoking the plugin again.
+
+`usePlugin` still returns the raw MCP result, including metadata. Use it for data
+tools and unsupported flows. The new methods do not change existing CLI commands.
+Funding requests stop with `outcome: "unsupported"`, `reason: "funding_required"`,
+and a non-signing `pending_funding` response. They never reopen or submit a plan.
+
 ## Configuration
 
 Resolution order: explicit constructor options → environment → stored config.
@@ -192,10 +263,13 @@ pnpm install
 pnpm typecheck
 pnpm build           # tsup → dist/ (ESM + types + paybox bin)
 
-# Refresh the generated tool types from a running server (the source of truth):
-PAYBOX_MCP_URL=http://127.0.0.1:8080/mcp PAYBOX_API_KEY=pbx_live_… pnpm gen
+# Refresh the generated tool types from the MCP tool contract:
+pnpm gen
 ```
 
-The argument and response types in `src/generated.ts` mirror the server's MCP
-tool schemas (`schemars`-derived) and `server/src/models.rs`. `pnpm gen` reads the
-live `list_tools` schemas so the client can't drift from the server contract.
+The argument types in `src/types.generated.ts` come from
+`artifacts/contracts/mcp-tools-v1.json`, the committed list of core MCP tools and
+their input schemas. CI fails when the tools change and the file does not, or
+when this file is not regenerated from it. Refresh it with
+`PAYBOX_UPDATE_CONTRACTS=1 cargo test --lib mcp_tool_contract_matches_core_tools`
+in `server/`. Response types in `src/types.ts` track `server/src/models.rs`.