warrant-client 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# warrant-client
+
+Buy resources for an AI agent over x402 on Hedera: a permanent name, an email
+inbox it owns, a phone number, SMS, inference, and memory written to a file
+nobody can edit. One call at a time, in USDC, with no API key and no signup.
+
+```bash
+npm i warrant-client
+```
+
+```ts
+import { Warrant } from "warrant-client";
+
+const warrant = new Warrant({
+  accountId: process.env.WARRANT_ACCOUNT_ID!,
+  privateKey: process.env.WARRANT_PRIVATE_KEY!,
+});
+
+const { result, settlement } = await warrant.buy("inference", { prompt: "hello" });
+```
+
+The endpoint and the price come from the service's own catalogue, so a service
+that adds a resource does not need this package republished to stay usable.
+
+## Command line
+
+```bash
+export WARRANT_ACCOUNT_ID=0.0.10514332
+export WARRANT_PRIVATE_KEY=302e…
+
+npx warrant catalogue
+npx warrant buy inference --prompt "one line on Hedera"
+npx warrant read /v1/receipts?limit=3
+```
+
+## The one error that matters
+
+A payment settles before the resource runs, so an upstream failure can happen
+after the money moved. That comes back as a `WarrantError` with `settled: true`,
+and retrying it buys the failure twice.
+
+```ts
+try {
+  await warrant.buy("email.send", { from, to, subject, body });
+} catch (err) {
+  if (err instanceof WarrantError && err.settled) { /* paid, not delivered */ }
+  if (err instanceof WarrantError && err.free)    { /* safe to fix and repeat */ }
+}
+```
+
+## What it needs
+
+A Hedera account holding testnet USDC, token `0.0.429274`. It does **not** need
+HBAR: the facilitator sponsors the network fee.
+
+Full documentation, including every request shape and the on-chain spending
+limit, is at
+[`/skill.md`](https://warrant-api-production-e111.up.railway.app/skill.md).
+Source: https://github.com/martinvibes/warrant
+
+MIT.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * The command line, for the times a person or a script wants one call.
+ *
+ *   export WARRANT_ACCOUNT_ID=0.0.10514332
+ *   export WARRANT_PRIVATE_KEY=302e…
+ *   warrant catalogue
+ *   warrant buy inference --prompt "one line on Hedera"
+ *   warrant read /v1/receipts?limit=3
+ *
+ * Flags become the JSON body: --prompt hello turns into {"prompt":"hello"}. It
+ * keeps the surface the same as the API rather than inventing a second
+ * vocabulary for the same eight things.
+ */
+import { Warrant, WarrantError, DEFAULT_BASE_URL } from "./index.js";
+const USAGE = `warrant — buy resources for an agent over x402 on Hedera
+
+  warrant catalogue                       what is for sale, and the price
+  warrant buy <kind> [--field value …]    buy one call
+  warrant read <path>                     any free endpoint, e.g. /v1/receipts
+
+Environment
+  WARRANT_ACCOUNT_ID    the Hedera account paying, e.g. 0.0.10514332
+  WARRANT_PRIVATE_KEY   its private key, DER or hex
+  WARRANT_BASE_URL      a different service (default ${DEFAULT_BASE_URL})
+  WARRANT_AGENT_ADDRESS the agent's EVM address, needed by identity.mint
+
+Examples
+  warrant buy inference --prompt "summarise x402 in one line"
+  warrant buy memory.write --content "the peer at 0x7510 answers on scout@…"
+  warrant buy sms.send --from +18164961100 --to +14155550123 --text hello
+`;
+/** Turns --key value pairs into the request body, untyped as the API is. */
+function parseFlags(args) {
+    const body = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith("--"))
+            continue;
+        const [name, inline] = arg.slice(2).split("=", 2);
+        if (!name)
+            continue;
+        const next = args[i + 1];
+        const raw = inline ?? (next && !next.startsWith("--") ? (i++, next) : "true");
+        body[name] = raw === "true" ? true : raw === "false" ? false : /^-?\d+$/.test(raw) ? Number(raw) : raw;
+    }
+    return body;
+}
+function client() {
+    const accountId = process.env.WARRANT_ACCOUNT_ID;
+    const privateKey = process.env.WARRANT_PRIVATE_KEY;
+    if (!accountId || !privateKey) {
+        fail("Set WARRANT_ACCOUNT_ID and WARRANT_PRIVATE_KEY to the Hedera account that pays.");
+    }
+    return new Warrant({ accountId: accountId, privateKey: privateKey, baseUrl: process.env.WARRANT_BASE_URL });
+}
+function fail(message) {
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+}
+function print(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+function row(offer) {
+    return `  ${offer.kind.padEnd(17)} ${offer.price.padStart(6)}   ${offer.title} · ${offer.poweredBy}`;
+}
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        process.stdout.write(USAGE);
+        return;
+    }
+    // Reading the catalogue costs nothing and needs no key, so it must work
+    // before an account exists. Anything else builds a paying client first.
+    if (command === "catalogue") {
+        const base = (process.env.WARRANT_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        const catalogue = (await (await fetch(`${base}/v1/catalogue`)).json());
+        process.stdout.write(`${base}\n  settles in ${catalogue.asset}\n\n`);
+        catalogue.offers.filter((o) => o.live).forEach((o) => process.stdout.write(`${row(o)}\n`));
+        return;
+    }
+    if (command === "read") {
+        const path = rest[0];
+        if (!path)
+            fail("Give a path, e.g. warrant read /v1/receipts?limit=3");
+        const base = (process.env.WARRANT_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        print(await (await fetch(`${base}${path.startsWith("/") ? path : `/${path}`}`)).json());
+        return;
+    }
+    if (command === "buy") {
+        const kind = rest[0];
+        if (!kind || kind.startsWith("--"))
+            fail("Say what to buy, e.g. warrant buy inference --prompt hello");
+        const purchase = await client().buy(kind, parseFlags(rest.slice(1)), process.env.WARRANT_AGENT_ADDRESS);
+        print(purchase);
+        return;
+    }
+    fail(`No command "${command}".\n\n${USAGE}`);
+}
+main().catch((err) => {
+    if (err instanceof WarrantError) {
+        // The settled flag is the one thing a script must not miss, so it is said
+        // in words rather than left in a JSON field nobody reads.
+        const paid = err.settled
+            ? "\nYou were charged. The resource failed after the payment settled. Do not retry blind."
+            : "\nYou were not charged.";
+        fail(`${err.message}${paid}`);
+    }
+    fail(err instanceof Error ? err.message : String(err));
+});

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/** Where the reference service lives. Point elsewhere with `baseUrl`. */
+export declare const DEFAULT_BASE_URL = "https://warrant-api-production-e111.up.railway.app";
+export type Network = "hedera:testnet" | "hedera:mainnet";
+export interface WarrantOptions {
+    /** The Hedera account the payments are signed from, e.g. "0.0.10514332". */
+    accountId: string;
+    /** That account's private key, DER or hex. Read it from the environment. */
+    privateKey: string;
+    baseUrl?: string;
+    network?: Network;
+}
+/** One row of `GET /v1/catalogue`. */
+export interface Offer {
+    kind: string;
+    title: string;
+    blurb: string;
+    poweredBy: string;
+    method: string;
+    path: string;
+    /** Display price, e.g. "$0.02". */
+    price: string;
+    /** Atomic units of a 6-decimal token, as a string. */
+    priceAtomic: string;
+    live: boolean;
+}
+export interface Catalogue {
+    asset: string;
+    assetDecimals: number;
+    network: string;
+    payTo: string;
+    facilitator: string;
+    offers: Offer[];
+    live: number;
+}
+export interface Purchase<T = unknown> {
+    kind: string;
+    result: T;
+    /** The Hedera transaction the payment settled in, when the service reports one. */
+    settlement?: string;
+}
+/**
+ * A call that failed.
+ *
+ * `settled` is the field that matters. When it is true the money has already
+ * moved and the resource did not arrive, so a retry buys the failure twice.
+ */
+export declare class WarrantError extends Error {
+    readonly status: number;
+    readonly kind: string | undefined;
+    /** True only when payment settled and the resource then failed. */
+    readonly settled: boolean;
+    readonly body: unknown;
+    constructor(message: string, status: number, kind: string | undefined, 
+    /** True only when payment settled and the resource then failed. */
+    settled: boolean, body: unknown);
+    /** True when nothing was charged, so the call is safe to correct and repeat. */
+    get free(): boolean;
+}
+export declare class Warrant {
+    readonly baseUrl: string;
+    readonly network: Network;
+    private readonly fetch;
+    private readonly accountId;
+    private catalogue?;
+    constructor(options: WarrantOptions);
+    /** What is for sale, and at what price. Free, and cached for this instance. */
+    offers(refresh?: boolean): Promise<Catalogue>;
+    /** One offer by kind, or undefined when this service does not sell it. */
+    offer(kind: string): Promise<Offer | undefined>;
+    /**
+     * Buys one call of `kind`.
+     *
+     * The endpoint and the method come from the catalogue rather than from a
+     * table in here, so a service that moves a path or adds a resource does not
+     * need this package republished to stay usable.
+     */
+    buy<T = unknown>(kind: string, body?: Record<string, unknown>, agentAddress?: string): Promise<Purchase<T>>;
+    /** Any free endpoint, e.g. "/v1/receipts?limit=5" or "/v1/agents/0.0.1234". */
+    read<T = unknown>(path: string): Promise<T>;
+}

package/dist/index.js

@@ -0,0 +1,154 @@
+/**
+ * A client for a Warrant service.
+ *
+ * The whole job is the three-step x402 exchange: call, be told the price, pay
+ * and call again. `@x402/fetch` already does that if you hand it a signer, so
+ * this is mostly the small honest parts around it — reading the catalogue so a
+ * caller can see a price before committing, and telling the two failure modes
+ * apart, because a purchase that settled and then failed upstream must never be
+ * retried blind.
+ *
+ *   const warrant = new Warrant({ accountId: "0.0.1234", privateKey: "302e…" });
+ *   const { result } = await warrant.buy("inference", { prompt: "hello" });
+ */
+import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
+import { ExactHederaScheme } from "@x402/hedera/exact/client";
+import { createClientHederaSigner, PrivateKey } from "@x402/hedera";
+/** Where the reference service lives. Point elsewhere with `baseUrl`. */
+export const DEFAULT_BASE_URL = "https://warrant-api-production-e111.up.railway.app";
+/**
+ * A call that failed.
+ *
+ * `settled` is the field that matters. When it is true the money has already
+ * moved and the resource did not arrive, so a retry buys the failure twice.
+ */
+export class WarrantError extends Error {
+    status;
+    kind;
+    settled;
+    body;
+    constructor(message, status, kind, 
+    /** True only when payment settled and the resource then failed. */
+    settled, body) {
+        super(message);
+        this.status = status;
+        this.kind = kind;
+        this.settled = settled;
+        this.body = body;
+        this.name = "WarrantError";
+    }
+    /** True when nothing was charged, so the call is safe to correct and repeat. */
+    get free() {
+        return !this.settled;
+    }
+}
+export class Warrant {
+    baseUrl;
+    network;
+    fetch;
+    accountId;
+    catalogue;
+    constructor(options) {
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.network = options.network ?? "hedera:testnet";
+        this.accountId = options.accountId;
+        const signer = createClientHederaSigner(options.accountId, parseKey(options.privateKey), {
+            network: this.network,
+        });
+        const client = new x402Client().register(this.network, new ExactHederaScheme(signer));
+        this.fetch = wrapFetchWithPayment(fetch, client);
+    }
+    /** What is for sale, and at what price. Free, and cached for this instance. */
+    async offers(refresh = false) {
+        if (!this.catalogue || refresh) {
+            this.catalogue = await this.read("/v1/catalogue");
+        }
+        return this.catalogue;
+    }
+    /** One offer by kind, or undefined when this service does not sell it. */
+    async offer(kind) {
+        return (await this.offers()).offers.find((o) => o.kind === kind);
+    }
+    /**
+     * Buys one call of `kind`.
+     *
+     * The endpoint and the method come from the catalogue rather than from a
+     * table in here, so a service that moves a path or adds a resource does not
+     * need this package republished to stay usable.
+     */
+    async buy(kind, body = {}, agentAddress) {
+        const offer = await this.offer(kind);
+        if (!offer) {
+            const selling = (await this.offers()).offers.map((o) => o.kind).join(", ");
+            throw new WarrantError(`${this.baseUrl} does not sell "${kind}". It sells: ${selling}.`, 404, kind, false, undefined);
+        }
+        const headers = {
+            "content-type": "application/json",
+            "x-agent": this.accountId,
+        };
+        // Only resources that write to a contract need it, and only the caller
+        // knows the address, so it is passed rather than guessed.
+        if (agentAddress)
+            headers["x-agent-address"] = agentAddress;
+        const response = await this.fetch(`${this.baseUrl}${offer.path}`, {
+            method: offer.method,
+            headers,
+            body: JSON.stringify(body),
+        });
+        const payload = await json(response);
+        if (!response.ok)
+            throw errorFrom(response, payload, kind);
+        const settlement = settlementFrom(response);
+        return { ...payload, ...(settlement ? { settlement } : {}) };
+    }
+    /** Any free endpoint, e.g. "/v1/receipts?limit=5" or "/v1/agents/0.0.1234". */
+    async read(path) {
+        const response = await fetch(`${this.baseUrl}${path}`);
+        const payload = await json(response);
+        if (!response.ok)
+            throw errorFrom(response, payload, undefined);
+        return payload;
+    }
+}
+/** Accepts a DER key or a raw hex one, because both are in circulation. */
+function parseKey(key) {
+    const trimmed = key.trim();
+    return trimmed.startsWith("302")
+        ? PrivateKey.fromStringDer(trimmed)
+        : PrivateKey.fromStringECDSA(trimmed.replace(/^0x/, ""));
+}
+async function json(response) {
+    const text = await response.text();
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function errorFrom(response, payload, fallbackKind) {
+    const body = (payload ?? {});
+    const settled = body.settled === true;
+    const message = body.error ??
+        body.hint ??
+        (response.status === 402
+            ? "Payment was required and none was accepted. Check the account holds USDC."
+            : `${response.status} from ${response.url}`);
+    return new WarrantError(message, response.status, body.kind ?? fallbackKind, settled, payload);
+}
+/** The settlement reference the service returns beside a successful purchase. */
+function settlementFrom(response) {
+    const header = response.headers.get("payment-response");
+    if (!header)
+        return undefined;
+    try {
+        const decoded = JSON.parse(Buffer.from(header, "base64").toString("utf8"));
+        const ref = decoded.transaction ?? decoded.settlement ?? decoded.txHash;
+        return typeof ref === "string" ? ref : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "warrant-client",
+  "version": "0.1.0",
+  "description": "Buy resources for an AI agent over x402 on Hedera: a name, an inbox, a phone number, inference and permanent memory, one call at a time.",
+  "keywords": ["x402", "agent", "hedera", "usdc", "pay-per-call", "ai-agent", "402"],
+  "license": "MIT",
+  "author": "martinvibes",
+  "homepage": "https://github.com/martinvibes/warrant#readme",
+  "repository": { "type": "git", "url": "git+https://github.com/martinvibes/warrant.git", "directory": "client" },
+  "bugs": "https://github.com/martinvibes/warrant/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
+  "bin": { "warrant": "dist/cli.js" },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@x402/core": "2.25.0",
+    "@x402/fetch": "2.25.0",
+    "@x402/hedera": "2.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2"
+  }
+}