@tempoxyz/patron 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# patron
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Your AI agents pay every website they read: $0.001 a page, in OUSD on Tempo, privately.
+
+```sh
+npx @tempoxyz/patron
+```
+
+First run signs you in with Tempo Wallet, asks for a monthly budget (default $5), buys
+tokens and adds a hook to Claude Code. After that, every page Claude Code fetches pays its
+site one token. Nothing stays running: the hook runs once per read and exits, and when
+tokens run low it starts a one-shot purchase that exits when done.
+
+Run `npx @tempoxyz/patron` again for status (tokens left, pages paid, budget used, rank) and to pause,
+change the budget or uninstall.
+
+## Commands
+
+| Command | What it does |
+| :- | :- |
+| `patron` | Set up, or show status and options |
+| `patron status` | Tokens left, pages paid this month, budget used, leaderboard rank |
+| `patron pause` / `patron resume` | Stop or restart paying |
+| `patron budget <usd>` | Change the monthly budget |
+| `patron tip <url> [usd]` | Tip a site, $0.10 by default |
+| `patron name <handle>` | Set your public leaderboard name |
+| `patron uninstall` | Remove agent hooks, optionally local data |
+| `patron hook` | Run by agents after each web read |
+
+## Privacy
+
+Tokens are Privacy Pass blind tokens (RFC 9578). The gateway knows your address bought a
+number of tokens, but cannot link a token to you when it is spent. Each read sends one token
+and the site's domain through an Oblivious HTTP relay (RFC 9458): the relay sees your IP but
+not the content; the gateway sees the content but not your IP.
+
+Local state lives in `~/.patron`: settings, tokens encrypted with AES-256-GCM under a key
+file readable only by you, and this month's per-site counts, which never leave the machine.
+
+## Budget
+
+The budget caps purchases: Patron never buys more than the monthly budget's worth of tokens
+in a calendar month. With Tempo Wallet, the access key Patron holds also has a spending
+limit equal to the budget, renewed every 30 days.
+
+## Agents
+
+| Agent | Hook |
+| :- | :- |
+| Claude Code | Async `PostToolUse` hook for WebFetch and WebSearch in `~/.claude/settings.json` |
+
+Codex runs web search as a hosted tool that hooks do not see, and Cursor and Amp have no
+documented hook for web reads, so they are not supported yet.
+
+## Environment
+
+| Variable | Default |
+| :- | :- |
+| `PATRON_HOME` | `~/.patron` |
+| `PATRON_GATEWAY_URL` | `https://patron-gateway.tempo-dev.workers.dev` |
+| `PATRON_RELAY_URL` | `https://patron-relay.tempo-dev.workers.dev` |
+| `PATRON_NETWORK` | `mainnet` (or `testnet`) |
+| `PATRON_PRIVATE_KEY` | unset; a testnet key instead of Tempo Wallet, for automation |
+| `PATRON_BUDGET_USD` | `5`, for non-interactive setup |
+| `PATRON_HOOK_COMMAND` | resolved at setup; overrides the hook command |

package/dist/bin.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { createRequire as __patronCreateRequire } from 'node:module'
+const require = __patronCreateRequire(import.meta.url)
+
+// src/bin.ts
+if (process.argv[2] === "hook") {
+  const { runHookProcess } = await import("./chunks/hook-process-QQ34YQIA.js");
+  await runHookProcess().catch(() => void 0);
+  process.exit(0);
+} else {
+  const { run } = await import("./chunks/-MVQH5G3L.js");
+  process.exitCode = await run(process.argv.slice(2));
+}