taximeter 0.1.0

package/dist/ui/assets/index-De4zKRDL.css

@@ -0,0 +1 @@
+:root{color-scheme:light;--background: #f6f8f5;--surface: #ffffff;--surface-muted: #edf1ed;--text: #182b25;--muted: #60736a;--faint: #798b81;--border: #dce4dd;--border-strong: #becdc1;--accent: #237d5c;--accent-soft: #d9ece1;--warning: #8b6819;--warning-soft: #f7efd9;--danger: #a74335;--danger-soft: #fff0eb;--chart-grid: #e8ede8;--font-ui: "Inter", "Aptos", "Segoe UI", Arial, sans-serif;--font-mono: "JetBrains Mono", "Cascadia Code", "SFMono-Regular", Consolas, monospace;font-family:var(--font-ui);font-size:14px;color:var(--text);background:var(--background);font-synthesis:none;text-rendering:optimizeLegibility;-webkit-font-smoothing:antialiased}@media(prefers-color-scheme:dark){:root{color-scheme:dark;--background: #101b16;--surface: #16231c;--surface-muted: #1c2c23;--text: #e4ede5;--muted: #a0b4a6;--faint: #82998a;--border: #2d4033;--border-strong: #49604f;--accent: #74c6a0;--accent-soft: #243f32;--warning: #dfbe73;--warning-soft: #38301c;--danger: #f29782;--danger-soft: #35241f;--chart-grid: #24372b}}*{box-sizing:border-box}body{margin:0;background:var(--background)}button,input,select{font:inherit}button,select{color:var(--text)}button,a,select{-webkit-tap-highlight-color:transparent}button{cursor:pointer}a{color:inherit;text-decoration:none}a:hover{color:var(--accent)}button:focus-visible,a:focus-visible,select:focus-visible,summary:focus-visible{outline:2px solid var(--accent);outline-offset:4px}button,select{border-radius:3px}h1,h2,h3,p{margin:0}h1{font-size:24px;font-weight:550;letter-spacing:-.9px;line-height:1.2}h2{font-size:14px;font-weight:600;letter-spacing:-.15px}h3{font-size:14px;font-weight:550}strong{font-weight:600}code,.mono,.numeric{font-family:var(--font-mono);font-variant-numeric:tabular-nums}.mono{letter-spacing:-.4px}.numeric{text-align:right;white-space:nowrap}.muted,.secondary-label{color:var(--muted);font-weight:400}.eyebrow{display:block;font-size:10px;font-weight:650;letter-spacing:1.25px;color:var(--muted);line-height:1.5}.masthead{min-height:66px;padding:0 36px;display:flex;align-items:center;justify-content:space-between;gap:18px;background:var(--surface);border-bottom:1px solid var(--border)}.brand{display:flex;align-items:center;gap:24px;min-width:0}.wordmark{display:inline-flex;align-items:center;gap:10px;font-size:22px;font-weight:650;letter-spacing:-1px;line-height:1;color:var(--text)}.mark{display:flex;align-items:flex-end;width:22px;height:21px;gap:3px}.mark i{display:block;width:5px;background:var(--accent)}.mark i:nth-child(1){height:9px}.mark i:nth-child(2){height:15px}.mark i:nth-child(3){height:21px}.brand-description{color:var(--muted);font-size:12px;padding-left:24px;border-left:1px solid var(--border)}.connection-state{display:flex;align-items:center;gap:7px;color:var(--muted);font-size:11px;white-space:nowrap}.live-dot{width:6px;height:6px;border-radius:50%;background:var(--accent)}.connection-offline .live-dot{background:var(--danger)}.connection-connecting .live-dot{background:var(--warning)}.navigation{display:flex;align-items:stretch;gap:26px;padding:0 36px;min-height:45px;border-bottom:1px solid var(--border);background:var(--surface);overflow-x:auto}.navigation button{border:0;border-radius:0;border-bottom:2px solid transparent;background:transparent;color:var(--muted);padding:0 1px;font-size:12px;white-space:nowrap;flex-shrink:0}.navigation button:hover{color:var(--text)}.navigation button[aria-current=page]{border-bottom-color:var(--accent);color:var(--accent);font-weight:600}.nav-date{margin-left:auto;align-self:center;padding-left:18px;font-size:11px;color:var(--muted);white-space:nowrap}main{max-width:1600px;padding:23px 36px 0;margin:0 auto}.page-heading{display:flex;align-items:flex-end;justify-content:space-between;gap:20px;margin-bottom:22px}.page-heading .eyebrow{margin-bottom:6px}.asset-selector{display:flex;align-items:center;gap:10px;flex-shrink:0}.asset-selector label{font-size:11px;color:var(--muted)}.asset-selector select{padding:7px 28px 7px 10px;border:1px solid var(--border-strong);background:var(--surface);font-size:12px;max-width:340px}.connection-warning{color:var(--danger);background:var(--danger-soft);border-left:3px solid var(--danger);padding:11px 14px;margin-bottom:18px;font-size:12px}.budget-hero{display:grid;grid-template-columns:minmax(0,1.22fr) minmax(280px,.78fr);align-items:center;gap:55px;padding:0 0 19px;border-bottom:1px solid var(--border-strong)}.hero-value{min-width:0}.hero-number{font-size:clamp(27px,3.2vw,44px);line-height:1.2;letter-spacing:-2px;color:var(--accent);margin:7px 0 8px;overflow-x:auto;white-space:nowrap;padding-bottom:2px}.hero-unit{color:var(--muted);font-size:14px;letter-spacing:0;margin-left:13px}.hero-value p{font-size:10px;color:var(--muted);overflow-wrap:anywhere}.budget-detail{padding-top:10px}.budget-caption{display:flex;justify-content:space-between;align-items:baseline;gap:15px;font-size:11px}.budget-caption .mono{overflow-wrap:anywhere}.budget-track{height:7px;background:var(--surface-muted);border:1px solid var(--border);margin:12px 0 10px;overflow:hidden}.budget-track>span{display:block;height:100%;background:var(--accent)}.budget-caption.below{color:var(--muted);font-size:10px}:where(.budget-caption.below) strong{color:var(--text);font-weight:500}.scope-note{color:var(--faint);font-size:10px;margin-top:10px}.totals-strip{display:flex;align-items:center;gap:25px;font-size:10px;color:var(--muted);padding:10px 0 12px;border-bottom:1px solid var(--border);flex-wrap:wrap}.totals-strip>span{display:inline-flex;gap:8px;align-items:baseline}.totals-strip strong{color:var(--text);font-size:11px;font-weight:500}.totals-strip .blocked-count{margin-left:auto}.section-heading{display:flex;align-items:center;justify-content:space-between;gap:18px;padding:16px 0 12px}.table-note{font-size:10px;color:var(--muted);white-space:nowrap}.table-scroll{overflow-x:auto;width:100%}table{width:100%;border-collapse:collapse;font-size:12px}th{text-align:left;font-size:10px;color:var(--muted);font-weight:550;border-top:1px solid var(--border-strong);border-bottom:1px solid var(--border-strong);padding:8px 10px;background:var(--surface-muted);white-space:nowrap}td{padding:8px 10px;border-bottom:1px solid var(--border);vertical-align:middle}th:first-child,td:first-child{padding-left:13px}th:last-child,td:last-child{padding-right:13px}.event-table{table-layout:fixed;min-width:850px;font-size:11px}.event-table th:nth-child(1){width:82px}.event-table th:nth-child(2){width:22%}.event-table th:nth-child(3){width:23%}.event-table th:nth-child(4){width:110px}.event-table th:nth-child(5){width:145px}.event-table th:nth-child(6){width:70px}.event-table th:nth-child(7){width:85px}.event-table td{padding-top:2px;padding-bottom:2px;line-height:16px;height:20px}.event-table tbody tr:hover{background:var(--surface)}.event-table .resource-cell,.event-table .attribution-cell,.event-table .asset-cell{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.event-table .resource-cell a:hover{text-decoration:underline;text-underline-offset:3px}.network-cell,.time-cell{color:var(--muted)}.event-table .numeric{overflow:hidden;text-overflow:ellipsis}.status-cell{text-align:right}.event-status{font-size:10px;white-space:nowrap}.status-confirmed{color:var(--muted)}.status-unknown{color:var(--warning)}.status-failed{color:var(--muted)}.status-blocked{color:var(--danger);font-weight:600}.event-table .blocked-row{background:var(--danger-soft)}.blocked-row td:first-child{border-left:3px solid var(--danger);padding-left:10px}.ledger-footnote{font-size:10px;color:var(--muted);line-height:1.7;padding-top:11px}.empty-state{background:var(--surface);border:1px solid var(--border);margin:25px 0 22px;padding:34px 32px 0;display:grid;grid-template-columns:minmax(0,1fr) minmax(0,.95fr);column-gap:58px}.empty-heading h2{font-size:26px;font-weight:500;letter-spacing:-.8px;max-width:320px;margin:10px 0 13px}.empty-heading p{font-size:12px;color:var(--muted);line-height:1.8;max-width:430px}.connection-instructions{padding-left:28px;border-left:1px solid var(--border)}.connection-instructions>code{display:block;font-size:18px;color:var(--accent);margin:12px 0 16px;letter-spacing:-.5px;overflow-wrap:anywhere}.connection-instructions p{font-size:11px;line-height:1.8;color:var(--muted)}.connection-instructions strong{font-weight:500;overflow-wrap:anywhere}.connection-instructions .connection-limit{margin-top:12px}.empty-footer{grid-column:1 / -1;border-top:1px solid var(--border);margin-top:30px;padding:14px 0;display:flex;align-items:center;justify-content:space-between;gap:20px;color:var(--muted);font-size:10px}.group-section,.timeline-section,.export-section{border-top:1px solid var(--border-strong)}.group-table{min-width:650px}.group-table th button{border:0;padding:0;background:transparent;font:inherit;color:inherit}.group-table td{padding-top:17px;padding-bottom:17px}.group-name{max-width:420px;overflow-wrap:anywhere;font-size:13px}.group-bar-cell{width:28%}.group-bar{height:5px;background:var(--surface-muted);min-width:90px}.group-bar span{display:block;height:100%;background:var(--accent)}.quiet-empty{background:var(--surface);border:1px solid var(--border);padding:36px 25px;margin:14px 0}.quiet-empty h3{margin-bottom:8px;font-size:18px}.quiet-empty p{font-size:12px;color:var(--muted);line-height:1.7}.chart-heading{display:flex;align-items:baseline;justify-content:space-between;gap:20px;margin:18px 0 5px}.chart-heading h3{font-size:12px;color:var(--muted)}.chart-heading .mono{color:var(--accent);font-size:14px}.chart-scroll{overflow-x:auto}.chart{display:block;width:100%;min-width:660px}.chart text{fill:var(--muted);font:11px var(--font-mono);font-variant-numeric:tabular-nums}.chart-rule{stroke:var(--border-strong);stroke-width:1}.chart-grid{stroke:var(--chart-grid);stroke-width:1;stroke-dasharray:3 5}.sparkline{fill:none;stroke:var(--accent);stroke-width:2;vector-effect:non-scaling-stroke;stroke-linejoin:round}.chart-dot,.hour-bar{fill:var(--accent)}.hourly-heading{border-top:1px solid var(--border);padding-top:20px;margin-top:8px;font-size:11px}.hourly-chart{margin-top:8px}.section-intro{color:var(--muted);font-size:12px;line-height:1.8;max-width:700px;margin:2px 0 23px}.export-options{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:15px;margin-bottom:30px}.export-option{display:flex;flex-direction:column;gap:14px;padding:22px;border:1px solid var(--border-strong);background:var(--surface);min-height:192px}.export-option:hover{border-color:var(--accent);color:var(--text)}.export-option>strong{font-size:24px;letter-spacing:-.5px;font-weight:500;display:flex;justify-content:space-between}.download-arrow{color:var(--accent);font-size:23px}.export-option>span:not(.eyebrow){font-size:11px;color:var(--muted);line-height:1.6}.export-option>span.download-label{margin-top:auto;color:var(--accent);font-weight:600;padding-top:7px}.statement-preview{background:var(--surface);border:1px solid var(--border);padding:26px}.preview-heading{display:flex;align-items:center;justify-content:space-between;gap:20px;margin-bottom:24px}.preview-heading>span{font-size:10px;color:var(--muted);letter-spacing:1px}.preview-summary{display:flex;gap:24px;flex-wrap:wrap;color:var(--muted);font-size:11px;margin-bottom:22px}.preview-summary strong{margin-left:8px;color:var(--text)}.statement-preview table{min-width:700px}.contract-address{display:block;font-family:var(--font-mono);color:var(--faint);font-size:9px;margin-top:5px}.diagnostics{border-top:1px solid var(--border);margin-top:22px;font-size:11px}.diagnostics summary{cursor:pointer;padding:13px 0}.diagnostics .mono{font-size:10px;margin-left:7px}.diagnostics ul{list-style:none;padding:0;margin:0 0 15px}.diagnostics li{display:grid;grid-template-columns:75px 145px 1fr;gap:14px;padding:8px 12px;border-bottom:1px solid var(--border);line-height:1.7}.diagnostics li>span{color:var(--muted)}.diagnostics li strong{font-weight:500;color:var(--warning)}.page-footer{display:flex;align-items:center;gap:15px;flex-wrap:wrap;margin-top:25px;padding:15px 0 18px;border-top:1px solid var(--border);color:var(--faint);font-size:9px;line-height:1.7}.page-footer>span:nth-child(2){margin-left:auto}.page-footer>.mono{margin-left:6px}.loading-shell{max-width:580px;margin:15vh auto 0;padding:30px}.loading-shell>.wordmark{margin-bottom:50px}.loading-shell h1{margin:10px 0 16px;font-size:30px}.loading-shell p{color:var(--muted);line-height:1.8;font-size:13px}.loading-shell>code{display:block;color:var(--accent);border:1px solid var(--border);padding:15px;margin-top:28px;background:var(--surface)}@media(min-width:1600px){.masthead,.navigation{padding-left:max(36px,calc((100vw - 1528px)/2));padding-right:max(36px,calc((100vw - 1528px)/2))}}@media(max-width:900px){.masthead,.navigation{padding-left:24px;padding-right:24px}main{padding-left:24px;padding-right:24px}.brand-description{display:none}.budget-hero{gap:28px;grid-template-columns:minmax(0,1fr) minmax(260px,1fr)}.totals-strip{gap:10px 20px}.empty-state{column-gap:26px;padding-left:24px;padding-right:24px}.empty-heading h2{font-size:22px}.empty-footer{align-items:flex-start}.export-option{padding:18px}}@media(max-width:600px){.masthead{padding:0 19px;min-height:61px}.wordmark{font-size:21px}.connection-state{font-size:10px}.navigation{gap:23px;padding:0 19px;min-height:43px}.navigation button{font-size:12px}.nav-date{display:none}main{padding:22px 19px 0}.page-heading{align-items:flex-start;flex-direction:column;gap:17px;margin-bottom:23px}h1{font-size:23px;letter-spacing:-.75px}.asset-selector{justify-content:space-between;width:100%}.asset-selector select{max-width:265px;flex:1}.budget-hero{grid-template-columns:minmax(0,1fr);gap:18px;padding-bottom:18px}.hero-number{font-size:34px;letter-spacing:-1.6px}.hero-unit{font-size:12px;margin-left:9px}.hero-value p{font-size:9px}.budget-detail{padding-top:0}.budget-caption{font-size:10px}.scope-note{margin-top:8px}.totals-strip{display:grid;grid-template-columns:1fr 1fr;gap:12px 18px;padding:16px 0}.totals-strip>span{flex-direction:column;gap:3px;min-width:0}.totals-strip strong{overflow-wrap:anywhere}.totals-strip .blocked-count{margin-left:0}.section-heading{gap:10px;padding-top:20px}.table-note{font-size:9px}.event-table{min-width:780px}.event-table td{padding-top:5px;padding-bottom:5px}.ledger-footnote{font-size:10px;line-height:1.8}.empty-state{grid-template-columns:minmax(0,1fr);padding:26px 22px 0;margin-top:23px}.empty-heading h2{font-size:24px;max-width:260px}.empty-heading p{font-size:12px;line-height:1.8}.connection-instructions{margin-top:24px;padding:23px 0 0;border-left:0;border-top:1px solid var(--border)}.connection-instructions>code{font-size:16px}.empty-footer{flex-direction:column;gap:6px;margin-top:25px;font-size:9px}.chart-heading{flex-direction:column;gap:8px}.chart{min-width:630px}.export-options{grid-template-columns:minmax(0,1fr);gap:12px}.export-option{min-height:176px;padding:21px}.section-intro{font-size:12px}.statement-preview{padding:19px}.preview-heading{flex-direction:column;align-items:flex-start}.preview-summary{gap:12px;flex-direction:column}.diagnostics li{grid-template-columns:66px 1fr;gap:6px 10px;padding-left:0;padding-right:0}.diagnostics li>span:last-child{grid-column:1 / -1}.page-footer{align-items:flex-start;gap:6px;flex-direction:column;margin-top:24px}.page-footer>span:nth-child(2),.page-footer>.mono{margin-left:0}}

package/dist/ui/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="light dark" />
+    <meta name="description" content="A taximeter for your AI agents. Your local payment ledger." />
+    <title>Taximeter — Local ledger</title>
+    <script type="module" crossorigin src="/assets/index-DOE5bD9P.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-De4zKRDL.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/docs/RECORDING.md

@@ -0,0 +1,75 @@
+# Record the 20-second demo
+
+`demo.gif` is a 20-second recording of the included simulation running on Windows,
+captured on 2026-09-08. The simulation runs entirely against a local fixture and
+an in-memory ledger. Its signatures and settlement reports are synthetic.
+
+From a source checkout, prepare the built package:
+
+```sh
+npm ci
+npm run build
+node docs/demo.mjs
+```
+
+The simulation prints 20 allowed payments, the documented 402 block for payment
+21, and an exact total of `140` atomic units. It creates no wallet, key, or persistent
+ledger and closes its listeners when finished.
+
+## Captured Windows recording
+
+The shipped GIF captures an actual `cmd.exe` session through Windows ConPTY using
+[node-pty 1.1.0](https://github.com/microsoft/node-pty). The recorder types
+`node docs/demo.mjs`, stores the terminal's output with its original timing in an
+asciicast v2 file, and waits until 20 seconds have elapsed. It checks the block and
+exact ledger total in the captured output and requires the command shell to exit
+successfully. The terminal is 104 columns by 32 rows.
+
+[agg 1.9.0](https://github.com/asciinema/agg/releases/tag/v1.9.0) renders that capture
+using Consolas at 18 px, line height 1.1, the GitHub dark theme, and a 20 fps cap.
+The final frame is held long enough for the complete GIF to last 20 seconds.
+The resulting GIF is 1049×653 and 96,519 bytes. The final block response and ledger
+total remain visible together. No demo output is fabricated or replaced.
+
+The source capture and encoding tools are local development artifacts and are
+excluded from the repository and npm package. FFmpeg converts the GIF to an H.264
+MP4 with one padding row and column for even dimensions. The following recipes
+can reproduce the demonstration from a source checkout.
+
+## VHS
+
+Install VHS and its ffmpeg/ttyd prerequisites from the
+[official VHS instructions](https://github.com/charmbracelet/vhs#installation).
+Run from the repository root on a system supported by VHS (WSL is suitable on Windows):
+
+```sh
+vhs docs/demo.tape
+```
+
+The tape types exactly `node docs/demo.mjs`, then leaves the resulting block and
+total visible. It writes `docs/demo.gif` at 960×660. Review the output before
+committing the replacement; it must fit within the package's 2 MB tarball limit.
+
+## asciinema alternative
+
+With asciinema and agg installed from their official projects, record the same
+script and convert it:
+
+```sh
+mkdir -p tmp
+asciinema rec --cols 104 --rows 32 --command "node docs/demo.mjs" tmp/demo.cast
+agg tmp/demo.cast docs/demo.gif
+```
+
+This quick alternative uses agg's default final pause and produces a shorter GIF.
+For a 20-second result, increase `--last-frame-duration` by the difference between
+20 seconds and the measured GIF duration, then render again. The verified Windows
+rendering helper calculates that pause automatically.
+
+Run these commands in a POSIX shell or WSL. Do not enter account data,
+wallet material, or real payment authorizations while recording. The expected
+terminal script is only the local demo command above.
+
+The Windows ConPTY/agg recording above was executed and visually checked. The VHS
+and asciinema alternatives remain documented recipes, not verified Windows runs.
+Recording tools are optional and are not package dependencies.

package/docs/SDK.md

@@ -0,0 +1,192 @@
+# Taximeter SDK
+
+`withMeter` wraps a Node.js fetch transport with the same parser, SQLite ledger,
+and policy engine used by the proxy. It supports Node 20 or later and ESM. It
+does not start a proxy or dashboard, create a payment, or configure a wallet.
+
+This project has not published its first npm release yet. From a source
+checkout, run `npm ci` and `npm run build`, then save the examples at the
+repository root. Their `import "taximeter"` statements resolve the package's own
+built exports. To try it in another project, run `npm pack` after building,
+copy the resulting tarball there, and use
+`npm install ./taximeter-0.1.0.tgz`. After the first publication,
+`npm install taximeter` will install the registry release.
+
+## Try it locally
+
+After choosing an installation method above, save this complete example as
+`sdk-local.mjs`, then run `node sdk-local.mjs`.
+It starts a temporary HTTP server on loopback, sends one ordinary request, and
+closes both the server and an in-memory ledger. It makes no external requests.
+
+```javascript
+import { once } from "node:events";
+import { createServer } from "node:http";
+import { withMeter } from "taximeter";
+
+const upstream = createServer((request, response) => {
+  response.writeHead(200, { "Content-Type": "application/json" });
+  response.end(JSON.stringify({
+    task: request.headers["taximeter-task"],
+    agent: request.headers["taximeter-agent"],
+  }));
+});
+upstream.listen(0, "127.0.0.1");
+await once(upstream, "listening");
+const address = upstream.address();
+if (!address || typeof address === "string") {
+  throw new Error("Expected a local TCP listener");
+}
+
+const metered = withMeter(fetch, {
+  db: ":memory:",
+  taskId: "research",
+  agentId: "agent",
+});
+try {
+  const response = await metered(`http://127.0.0.1:${address.port}/example`, {
+    redirect: "error",
+  });
+  console.log(await response.text());
+  console.log(`Payments recorded: ${metered.ledger.events().length}`);
+} finally {
+  metered.close();
+  upstream.closeAllConnections();
+  await new Promise((resolve, reject) => {
+    upstream.close((error) => error ? reject(error) : resolve());
+  });
+}
+```
+
+Expected output:
+
+```text
+{"task":"research","agent":"agent"}
+Payments recorded: 0
+```
+
+An ordinary request is not a payment. Attribution headers travel with the
+request, but a ledger payment appears only when the transport sees a recognized
+x402 authorization. A 402 challenge alone also contributes no spend.
+
+## Place the meter inside the payment wrapper
+
+Use `wrapFetchWithPayment(withMeter(fetch, options), client)`. This placement
+lets Taximeter inspect the initial challenge and gate each signed replay before
+the supplied transport forwards it. Wrapping a payment-enabled fetch on the
+outside hides that wrapper's internal replay.
+
+The following ESM factory accepts your application's existing, configured
+`x402Client` or `x402HTTPClient`. It neither creates nor receives a private key.
+Install the optional integration dependency with
+`npm install @x402/fetch@2.25.0`, then save this module as `metered-payment.mjs`.
+Taximeter itself does not depend on the official payment client.
+
+```javascript
+import { wrapFetchWithPayment } from "@x402/fetch";
+import { withMeter } from "taximeter";
+
+/**
+ * @param {import("@x402/fetch").x402Client | import("@x402/fetch").x402HTTPClient} client
+ * @param {import("taximeter").MeterOptions} [options]
+ */
+export function createMeteredPaymentFetch(client, options = {}) {
+  const transport = withMeter(fetch, options);
+  return {
+    fetch: wrapFetchWithPayment(transport, client),
+    ledger: transport.ledger,
+    close: () => transport.close(),
+  };
+}
+```
+
+Pass your existing client and attribution options to
+`createMeteredPaymentFetch(client, { taskId: "research", agentId: "agent" })`.
+Use the returned `fetch` in place of your existing paid fetch, and call `close`
+after all requests have finished. Client setup and authorization remain your
+application's responsibility. Configuring the payment client to support a rail
+does not add that rail to Taximeter's supported subset.
+
+The factory's parameter types and composition match the published
+[@x402/fetch 2.25.0 declarations](https://unpkg.com/@x402/fetch@2.25.0/dist/esm/index.d.mts)
+and [transport implementation](https://unpkg.com/@x402/fetch@2.25.0/dist/esm/index.mjs).
+The local example and factory were exercised with ordinary loopback traffic;
+the integration tests use synthetic x402 authorizations. No wallet or genuine
+payment was used to validate these examples.
+
+## Options and lifecycle
+
+`withMeter(fetchImpl, options)` returns a fetch-compatible function with a
+`ledger` property and an idempotent `close()` method.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `db` | Resolved configuration; normally `~/.taximeter/ledger.db` | SQLite path. Use `:memory:` for temporary state. Overrides `config.db` when the wrapper creates the ledger. |
+| `config` | Resolved configuration | A partial Taximeter configuration, including budgets and policy. Amounts must be decimal integer strings in atomic units. |
+| `ledger` | A new `Ledger` | An existing Taximeter ledger owned by the caller. Its storage path is used instead of `db`. |
+| `taskId` | Existing `Taximeter-Task` header, otherwise unattributed | Overrides the task header on each request. Use an HTTP-header-compatible label of 1–256 characters. |
+| `agentId` | Existing `Taximeter-Agent` header, otherwise unattributed | Overrides the agent header on each request. Use an HTTP-header-compatible label of 1–256 characters. |
+
+Without an injected ledger, configuration resolves from home/cwd files and
+environment, with explicit SDK options taking precedence. See the
+[configuration reference](../README.md#configuration). With an injected
+`ledger`, the SDK uses built-in defaults plus `config`; it does not load config
+files or environment settings. Keep budgets consistent across writers sharing
+the same database.
+
+The wrapper closes only a ledger it created. For an injected ledger, close all
+wrappers after their requests finish, then let the owner close the ledger.
+Reusing a closed wrapper passes requests directly to the original transport
+without metering. Do not use a closed wrapper for later payments.
+
+## Fetch behavior and limits
+
+- Use a Node fetch implementation that accepts standard `string`, `URL`, or
+  `Request` inputs. Header objects, header tuples, and `Headers` are supported.
+  Request bodies, abort signals, and transport options are preserved.
+- The wrapper returns the original upstream `Response`. It does not consume
+  its body. It inspects a clone only for legacy 402 challenges, bounded to
+  64 KiB and 100 ms. Slow, oversized, malformed, or unsupported challenges pass
+  through with a diagnostic.
+- Native fetch or a custom transport can follow redirects internally. Those
+  hops are invisible to Taximeter's preflight policy checks. A redirected
+  response produces a diagnostic, but its destination may already have received
+  a payment header. Use `redirect: "error"` on host-sensitive fetch calls, or a
+  transport that exposes each hop separately. Taximeter preserves your redirect
+  setting. Redirected v1 challenges are not cached against the initial URL.
+- Internal retries hidden inside a custom transport have the same visibility
+  limit. Put payment retries outside the metered transport, as in the official
+  wrapper composition above.
+- Recognized authorizations reserve capacity before forwarding. A policy denial
+  returns a 402 JSON response with `error: "blocked_by_taximeter"`, `reason`,
+  `budget`, `spent`, and `remaining`, and records a blocked event. The enclosing
+  payment client can apply its own response handling or throw its own error.
+- If the transport throws after forwarding an authorization, the original
+  error is rethrown and the authorization remains reserved with unknown
+  settlement. Missing settlement evidence has the same conservative treatment.
+  Upstream-reported settlement is not independent on-chain verification.
+- Storage failures pass traffic through and emit a local stderr warning.
+  Enforcement requires working storage. Unsupported payment formats also pass
+  through with a diagnostic; this is a cooperative meter rather than an
+  isolation boundary.
+
+The initial adapter meters exact EVM EIP-3009 payments: legacy v1 on Base and
+Base Sepolia, and v2 with EVM CAIP-2 networks. Permit2, ERC-7710, other schemes,
+and other rails remain unmetered. Known Base/Base Sepolia USDC uses six decimal
+places; unknown tokens remain exact atomic units. Budgets and totals are
+separate for every network and asset. See [SPEC-NOTES](../SPEC-NOTES.md) for
+wire formats, challenge correlation, idempotency, and settlement rules.
+
+## Read the same ledger from the CLI
+
+For persistent state, use `db: "./agent.db"` in your SDK options. Run
+`npx taximeter report --db ./agent.db --json` to inspect exact totals, or
+`npx taximeter export --db ./agent.db --csv ./agent.csv` to create a statement.
+Export files must not already exist. Monetary CSV `amount` values are counted
+contributions; blocked and known failed rows contribute zero. Sum them
+separately by network and asset.
+
+Run `npx taximeter start --db ./agent.db` to view that ledger in the local
+dashboard. The SDK continues to call its own supplied transport; the CLI proxy
+and `config.upstream` do not reroute SDK requests. Stop all SDK writers before
+using `npx taximeter reset --db ./agent.db --yes`, which archives the ledger.

package/docs/demo.mjs

@@ -0,0 +1,145 @@
+import assert from "node:assert/strict";
+import { createServer, request } from "node:http";
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+import { closeProxy, createProxy, Ledger, parseConfig, totals } from "../dist/index.js";
+
+// Synthetic envelopes only: no signing, wallet, facilitator, or real payment.
+const asset = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
+const payTo = "0x209693bc6afc0c5328ba36faf03c514ef312287c";
+const payer = "0x857b06519e91e3a54538791bdbb0e22373e36b66";
+const encode = (value) => Buffer.from(JSON.stringify(value)).toString("base64");
+const accepted = {
+  scheme: "exact",
+  network: "eip155:8453",
+  asset,
+  payTo,
+  amount: "7",
+  maxTimeoutSeconds: 60,
+  extra: { name: "USD Coin", version: "2" },
+};
+const upstream = createServer((req, res) => {
+  const header = z.string().optional().parse(req.headers["payment-signature"]);
+  if (!header) {
+    const resource = z
+      .url()
+      .parse(`http://${z.string().parse(req.headers.host)}${z.string().parse(req.url)}`);
+    res.writeHead(402, {
+      "PAYMENT-REQUIRED": encode({
+        x402Version: 2,
+        resource: { url: resource },
+        accepts: [accepted],
+      }),
+    });
+    res.end("Synthetic offer");
+    return;
+  }
+  const payment = z
+    .object({ payload: z.object({ authorization: z.object({ nonce: z.string() }) }) })
+    .parse(JSON.parse(Buffer.from(header, "base64").toString("utf8")));
+  res.writeHead(200, {
+    "PAYMENT-RESPONSE": encode({
+      success: true,
+      network: "eip155:8453",
+      payer,
+      transaction: payment.payload.authorization.nonce,
+    }),
+  });
+  res.end("Synthetic settlement reported");
+});
+async function listen(server) {
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  return z.object({ port: z.number() }).parse(server.address()).port;
+}
+const ledger = new Ledger(":memory:");
+const proxy = createProxy({
+  ledger,
+  config: parseConfig({ budgets: { perTask: null, perAgent: null, global: { amount: "140" } } }),
+});
+try {
+  const upstreamPort = await listen(upstream);
+  const proxyPort = await listen(proxy);
+  const resource = `http://127.0.0.1:${upstreamPort}/data`;
+  const offer = await fetch(resource);
+  assert.equal(offer.status, 402);
+  const challenge = z
+    .object({
+      x402Version: z.literal(2),
+      resource: z.object({ url: z.url() }),
+      accepts: z.array(z.object({ amount: z.literal("7") })),
+    })
+    .parse(
+      JSON.parse(
+        Buffer.from(z.string().parse(offer.headers.get("payment-required")), "base64").toString(
+          "utf8",
+        ),
+      ),
+    );
+  assert.equal(challenge.resource.url, resource);
+  await offer.arrayBuffer();
+  console.log("Taximeter | local simulation | no money moves");
+  console.log("Budget: 140 atomic units. Each payment: 7 atomic units.");
+  for (let index = 1; index <= 21; index++) {
+    const payload = {
+      signature: `0x${"12".repeat(65)}`,
+      authorization: {
+        from: payer,
+        to: payTo,
+        value: "7",
+        validAfter: "0",
+        validBefore: "9999999999",
+        nonce: `0x${index.toString(16).padStart(64, "0")}`,
+      },
+    };
+    const result = await new Promise((resolve, reject) => {
+      const req = request(
+        {
+          hostname: "127.0.0.1",
+          port: proxyPort,
+          path: resource,
+          headers: {
+            "PAYMENT-SIGNATURE": encode({
+              x402Version: 2,
+              accepted,
+              resource: { url: resource },
+              payload,
+            }),
+            "Taximeter-Task": "demo",
+            "Taximeter-Agent": "local-fixture",
+          },
+        },
+        (res) => {
+          let body = "";
+          res.setEncoding("utf8");
+          res.on("data", (chunk) => {
+            body += z.string().parse(chunk);
+          });
+          res.on("error", reject);
+          res.on("end", () => resolve({ status: res.statusCode, body }));
+        },
+      );
+      req.on("error", reject);
+      req.end();
+    });
+    assert.equal(result.status, index <= 20 ? 200 : 402);
+    console.log(
+      `Payment ${index.toString().padStart(2)} | ${index <= 20 ? "allowed" : "BLOCKED"} | total ${totals(ledger.view())[0]?.amount} atomic units`,
+    );
+    if (index === 21) console.log(result.body);
+    await delay(80);
+  }
+  assert.equal(totals(ledger.view())[0]?.amount, "140");
+  assert.equal(ledger.events().filter((row) => row.status === "blocked").length, 1);
+  console.log("Exact ledger total: 140 atomic units. One blocked event recorded.");
+} finally {
+  if (proxy.listening) await closeProxy(proxy);
+  upstream.closeAllConnections();
+  if (upstream.listening) await new Promise((resolve) => upstream.close(resolve));
+  ledger.close();
+}

package/docs/demo.tape

@@ -0,0 +1,15 @@
+Output docs/demo.gif
+Set Shell "bash"
+Set FontSize 18
+Set Width 960
+Set Height 660
+Set TypingSpeed 50ms
+Set Padding 20
+Hide
+Type "clear"
+Enter
+Sleep 500ms
+Show
+Type "node docs/demo.mjs"
+Enter
+Sleep 18s

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "taximeter",
+  "version": "0.1.0",
+  "description": "A taximeter for your AI agents.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ding808/taximeter.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "taximeter": "dist/cli/index.js",
+    "txm": "dist/cli/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "CHANGELOG.md",
+    "DECISIONS.md",
+    "VERIFICATION.md",
+    "SPEC.md",
+    "SPEC-NOTES.md",
+    "taximeter.config.example.json",
+    "docs"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check --error-on-warnings .",
+    "format": "biome check --write .",
+    "test": "vitest run --coverage",
+    "build": "tsup && vite build",
+    "check:package": "node scripts/check-package.mjs",
+    "smoke:package": "node scripts/smoke-package.mjs",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "npm run build && changeset publish"
+  },
+  "dependencies": {
+    "better-sqlite3": "12.8.0",
+    "commander": "13.1.0",
+    "uuid": "11.1.1",
+    "zod": "4.5.4"
+  },
+  "overrides": {
+    "tsup": {
+      "esbuild": "0.28.1"
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.12",
+    "@changesets/cli": "2.29.8",
+    "@types/better-sqlite3": "9.6.0",
+    "@types/node": "22.20.1",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.7",
+    "@vitest/coverage-v8": "3.2.7",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vite": "6.4.3",
+    "vitest": "3.2.7"
+  }
+}

package/taximeter.config.example.json

@@ -0,0 +1,16 @@
+{
+  "budgets": {
+    "perTask": { "amount": "5000000", "asset": "USDC" },
+    "perAgent": { "amount": "50000000", "asset": "USDC", "window": "24h" },
+    "global": { "amount": "100000000", "asset": "USDC", "window": "24h" }
+  },
+  "policy": {
+    "allowHosts": [],
+    "denyHosts": [],
+    "allowPayTo": [],
+    "maxSinglePayment": "1000000",
+    "maxSingleAsset": "USDC"
+  },
+  "ports": { "proxy": 8402, "dashboard": 8403 },
+  "db": "~/.taximeter/ledger.db"
+}