@toon-protocol/client 0.9.2 → 0.11.0

package/dist/index.js

@@ -6,7 +6,7 @@ import {
 } from "./chunk-WHAEQLIW.js";
 
 // src/ToonClient.ts
-import { generateSecretKey as generateSecretKey3, getPublicKey as getPublicKey2 } from "nostr-tools/pure";
+import { generateSecretKey as generateSecretKey3, getPublicKey as getPublicKey2, finalizeEvent } from "nostr-tools/pure";
 
 // src/config.ts
 import { generateSecretKey as generateSecretKey2 } from "nostr-tools/pure";
@@ -21,6 +21,7 @@ var ToonClientError = class extends Error {
     this.code = code;
     this.name = "ToonClientError";
   }
+  code;
 };
 var NetworkError = class extends ToonClientError {
   constructor(message, cause) {
@@ -1352,6 +1353,232 @@ var BtpRuntimeClient = class {
   }
 };
 
+// src/adapters/HttpIlpClient.ts
+var ILP_CLAIM_HEADER = "ILP-Payment-Channel-Claim";
+var ILP_CLAIM_WRAPPED_HEADER = "ILP-Payment-Channel-Claim-Wrapped";
+var ILP_PEER_ID_HEADER = "ILP-Peer-Id";
+var HttpIlpClient = class {
+  httpEndpoint;
+  peerId;
+  authToken;
+  timeout;
+  retryConfig;
+  httpClient;
+  createWebSocket;
+  constructor(config) {
+    this.httpEndpoint = config.httpEndpoint;
+    this.peerId = config.peerId;
+    this.authToken = config.authToken;
+    this.timeout = config.timeout ?? 3e4;
+    this.retryConfig = {
+      maxRetries: config.maxRetries ?? 3,
+      retryDelay: config.retryDelay ?? 1e3
+    };
+    this.httpClient = config.httpClient ?? fetch;
+    this.createWebSocket = config.createWebSocket;
+  }
+  /**
+   * Send an ILP PREPARE via `POST /ilp` WITHOUT a claim. The connector accepts
+   * this only on free/zero-amount routes; paid writes must use
+   * {@link sendIlpPacketWithClaim}. Satisfies the IlpClient interface.
+   */
+  async sendIlpPacket(params) {
+    return withRetry(() => this.postPrepare(params), {
+      maxRetries: this.retryConfig.maxRetries,
+      retryDelay: this.retryConfig.retryDelay,
+      exponentialBackoff: true,
+      shouldRetry: (error) => error instanceof NetworkError
+    });
+  }
+  /**
+   * Send an ILP PREPARE via `POST /ilp` with the payment-channel claim attached
+   * as the `ILP-Payment-Channel-Claim` header. `claim` is the SAME JSON object
+   * the BTP path attaches as the `payment-channel-claim` protocolData entry —
+   * we base64(JSON.stringify(claim)) it, byte-for-byte identical to BTP.
+   */
+  async sendIlpPacketWithClaim(params, claim) {
+    return withRetry(() => this.postPrepare(params, claim), {
+      maxRetries: this.retryConfig.maxRetries,
+      retryDelay: this.retryConfig.retryDelay,
+      exponentialBackoff: true,
+      shouldRetry: (error) => error instanceof NetworkError
+    });
+  }
+  /**
+   * Upgrade to a duplex BTP session over the SAME endpoint.
+   *
+   * Derives the `ws(s)://` URL from `httpEndpoint`, opens a WebSocket with
+   * `Sec-WebSocket-Protocol: btp` and the same `ILP-Peer-Id` + `Authorization`
+   * headers, and returns a connected {@link BtpRuntimeClient}. When auth headers
+   * are present the connector pre-authenticates the session (no in-band auth
+   * frame); without them the BtpRuntimeClient falls back to the normal BTP
+   * auth-frame flow.
+   *
+   * NOTE: passing per-connection headers + a subprotocol to a WebSocket is
+   * Node-only (the `ws` package). Browsers cannot set arbitrary request headers
+   * on a WebSocket handshake, so a browser consumer must use the gateway
+   * transport or BTP-with-auth-frame instead.
+   */
+  async upgradeToBtp() {
+    const btpUrl = httpEndpointToBtpUrl(this.httpEndpoint);
+    const createWebSocket = this.createWebSocket ?? await makeBtpWebSocketFactory(this.authHeaders());
+    const client = new BtpRuntimeClient({
+      btpUrl,
+      // BtpRuntimeClient sends an auth frame using these; when the connector
+      // pre-authenticated via Upgrade headers it accepts the (redundant) frame.
+      peerId: this.peerId ?? "client",
+      authToken: this.authToken ?? "",
+      createWebSocket
+    });
+    await client.connect();
+    return client;
+  }
+  // ─── Private ──────────────────────────────────────────────────────────────
+  authHeaders() {
+    const headers = {};
+    if (this.peerId) headers[ILP_PEER_ID_HEADER] = this.peerId;
+    if (this.authToken) headers["Authorization"] = `Bearer ${this.authToken}`;
+    return headers;
+  }
+  /**
+   * Single attempt: serialize the PREPARE, POST it, and map the response.
+   * @throws {NetworkError} On connection/timeout failures (retried).
+   * @throws {ConnectorError} On non-retryable transport errors (5xx / unexpected).
+   */
+  async postPrepare(params, claim) {
+    const requestTimeout = params.timeout ?? this.timeout;
+    const prepare = serializeIlpPrepare({
+      type: ILPPacketType.PREPARE,
+      amount: BigInt(params.amount),
+      destination: params.destination,
+      executionCondition: new Uint8Array(32),
+      expiresAt: new Date(Date.now() + requestTimeout),
+      data: fromBase64(params.data)
+    });
+    const headers = {
+      "Content-Type": "application/octet-stream",
+      ...this.authHeaders()
+    };
+    if (claim !== void 0) {
+      headers[ILP_CLAIM_HEADER] = toBase64(
+        encodeUtf8(JSON.stringify(claim))
+      );
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), requestTimeout);
+    try {
+      const response = await this.httpClient(this.httpEndpoint, {
+        method: "POST",
+        headers,
+        // Copy into a fresh ArrayBuffer so fetch sees a clean body, not a view.
+        body: prepare.slice(),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      return await this.mapResponse(response);
+    } catch (error) {
+      clearTimeout(timeoutId);
+      throw this.mapTransportError(error, requestTimeout);
+    }
+  }
+  /**
+   * Map a `200 OK` body (OER FULFILL/REJECT) to an IlpSendResult; map a non-2xx
+   * to a transport error. Per the wire contract, ILP-level rejects arrive as a
+   * 200 + REJECT body — only HTTP non-2xx means a transport-layer failure.
+   */
+  async mapResponse(response) {
+    if (response.ok) {
+      const buf = new Uint8Array(await response.arrayBuffer());
+      if (buf.length === 0) {
+        throw new ConnectorError("Empty 200 body from /ilp (expected OER ILP response)");
+      }
+      const ilp = deserializeIlpPacket(buf);
+      if (ilp.type === ILPPacketType.FULFILL) {
+        return {
+          accepted: true,
+          data: ilp.data.length > 0 ? toBase64(ilp.data) : void 0
+        };
+      }
+      return {
+        accepted: false,
+        code: ilp.code,
+        message: ilp.message,
+        data: ilp.data.length > 0 ? toBase64(ilp.data) : void 0
+      };
+    }
+    const body = await response.text().catch(() => "");
+    const detail = body ? `: ${body}` : "";
+    if (response.status >= 500) {
+      throw new ConnectorError(
+        `Connector transport error (${response.status} ${response.statusText})${detail}`
+      );
+    }
+    throw new ConnectorError(
+      `ILP-over-HTTP request rejected (${response.status} ${response.statusText})${detail}`
+    );
+  }
+  mapTransportError(error, requestTimeout) {
+    if (error instanceof ConnectorError || error instanceof NetworkError) {
+      return error;
+    }
+    if (error instanceof Error && error.name === "AbortError") {
+      return new NetworkError(`Request timeout after ${requestTimeout}ms`, error);
+    }
+    if (error instanceof TypeError && (error.message.includes("fetch failed") || error.message.includes("ECONNREFUSED") || error.message.includes("ECONNRESET") || error.message.includes("ETIMEDOUT") || error.message.includes("network"))) {
+      return new NetworkError(`Network connection failed: ${error.message}`, error);
+    }
+    return new ConnectorError(
+      `Unexpected error during ILP-over-HTTP request: ${error instanceof Error ? error.message : String(error)}`,
+      error instanceof Error ? error : void 0
+    );
+  }
+};
+function httpEndpointToBtpUrl(httpEndpoint) {
+  return httpEndpoint.replace(/^https:\/\//i, "wss://").replace(/^http:\/\//i, "ws://");
+}
+async function makeBtpWebSocketFactory(headers) {
+  const { createRequire } = await import("module");
+  const require2 = createRequire(import.meta.url);
+  const WS = require2("ws");
+  const ws = WS;
+  const WSClass = typeof ws === "function" ? ws : typeof ws.default === "function" ? ws.default : typeof ws.WebSocket === "function" ? ws.WebSocket : null;
+  if (WSClass === null) {
+    throw new Error(
+      "makeBtpWebSocketFactory: require('ws') did not yield a constructor on .default, .WebSocket, or the module root."
+    );
+  }
+  return (url) => (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    new WSClass(url, "btp", { headers })
+  );
+}
+
+// src/adapters/selectIlpTransport.ts
+function readDiscoveredIlpPeer(peer) {
+  const p = peer ?? {};
+  return {
+    btpEndpoint: typeof p["btpEndpoint"] === "string" ? p["btpEndpoint"] : void 0,
+    httpEndpoint: typeof p["httpEndpoint"] === "string" ? p["httpEndpoint"] : void 0,
+    supportsUpgrade: typeof p["supportsUpgrade"] === "boolean" ? p["supportsUpgrade"] : void 0
+  };
+}
+function selectIlpTransport(peer, options = {}) {
+  const needsDuplex = options.needsDuplex ?? false;
+  const http2 = peer.httpEndpoint?.trim() || void 0;
+  const btp = peer.btpEndpoint?.trim() || void 0;
+  const canUpgrade = peer.supportsUpgrade === true;
+  if (needsDuplex) {
+    if (btp) return { kind: "btp", btpEndpoint: btp };
+    if (http2 && canUpgrade) return { kind: "http-upgradable", httpEndpoint: http2 };
+    throw new Error(
+      "Duplex transport required but peer exposes neither a btpEndpoint nor an upgradable httpEndpoint"
+    );
+  }
+  if (http2) return { kind: "http", httpEndpoint: http2, canUpgrade };
+  if (btp) return { kind: "btp", btpEndpoint: btp };
+  throw new Error("Peer exposes neither an httpEndpoint nor a btpEndpoint");
+}
+
 // src/channel/OnChainChannelClient.ts
 import {
   createPublicClient,
@@ -2548,6 +2775,12 @@ async function initializeHttpMode(config) {
   const effectiveBtpUrl = transport.btpUrl ?? config.btpUrl;
   const effectiveConnectorUrl = transport.connectorUrl ?? config.connectorUrl;
   const settlementInfo = buildSettlementInfo(config);
+  const discoveredPeer = readDiscoveredIlpPeer({
+    btpEndpoint: effectiveBtpUrl,
+    httpEndpoint: config.connectorHttpEndpoint,
+    supportsUpgrade: config.connectorSupportsUpgrade
+  });
+  const transportChoice = discoveredPeer.httpEndpoint || discoveredPeer.btpEndpoint ? selectIlpTransport(discoveredPeer, { needsDuplex: false }) : null;
   let btpClient = null;
   if (effectiveBtpUrl) {
     btpClient = new BtpRuntimeClient({
@@ -2558,7 +2791,20 @@ async function initializeHttpMode(config) {
     });
     await btpClient.connect();
   }
-  const runtimeClient = btpClient ?? new HttpRuntimeClient({
+  let httpIlpClient = null;
+  if (transportChoice && (transportChoice.kind === "http" || transportChoice.kind === "http-upgradable")) {
+    httpIlpClient = new HttpIlpClient({
+      httpEndpoint: transportChoice.httpEndpoint,
+      ...config.btpPeerId !== void 0 ? { peerId: config.btpPeerId } : {},
+      ...config.btpAuthToken !== void 0 ? { authToken: config.btpAuthToken } : {},
+      timeout: config.queryTimeout,
+      maxRetries: config.maxRetries,
+      retryDelay: config.retryDelay,
+      ...transport.httpClient !== void 0 ? { httpClient: transport.httpClient } : {},
+      ...transport.createWebSocket !== void 0 ? { createWebSocket: transport.createWebSocket } : {}
+    });
+  }
+  const runtimeClient = httpIlpClient ?? btpClient ?? new HttpRuntimeClient({
     connectorUrl: effectiveConnectorUrl,
     timeout: config.queryTimeout,
     maxRetries: config.maxRetries,
@@ -3304,6 +3550,324 @@ var JsonFileChannelStore = class {
   }
 };
 
+// src/blob-storage.ts
+import { buildBlobStorageRequest } from "@toon-protocol/core";
+var ARWEAVE_TX_ID_REGEX = /^[A-Za-z0-9_-]{43}$/;
+async function requestBlobStorage(client, secretKey, params) {
+  const bid = params.bid ?? (params.ilpAmount !== void 0 ? String(params.ilpAmount) : void 0);
+  if (bid === void 0 || bid === "") {
+    return {
+      success: false,
+      error: "requestBlobStorage requires a bid (or ilpAmount to derive it)"
+    };
+  }
+  const blobBuffer = Buffer.from(
+    params.blobData.buffer,
+    params.blobData.byteOffset,
+    params.blobData.byteLength
+  );
+  let event;
+  try {
+    event = buildBlobStorageRequest(
+      {
+        blobData: blobBuffer,
+        contentType: params.contentType,
+        bid
+      },
+      secretKey
+    );
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+  const result = await client.publishEvent(event, {
+    destination: params.destination,
+    claim: params.claim,
+    ilpAmount: params.ilpAmount
+  });
+  if (!result.success) {
+    return {
+      success: false,
+      eventId: result.eventId ?? event.id,
+      error: result.error ?? "Blob storage request rejected"
+    };
+  }
+  if (!result.data) {
+    return {
+      success: false,
+      eventId: event.id,
+      error: "FULFILL contained no data; expected base64-encoded Arweave tx ID"
+    };
+  }
+  const txId = decodeUtf8(fromBase64(result.data));
+  if (!ARWEAVE_TX_ID_REGEX.test(txId)) {
+    return {
+      success: false,
+      eventId: event.id,
+      error: `Decoded FULFILL data is not a valid Arweave tx ID: "${txId}"`
+    };
+  }
+  return {
+    success: true,
+    txId,
+    eventId: event.id
+  };
+}
+
+// src/adapters/Http402Client.ts
+var Http402Client = class {
+  fetchImpl;
+  resolveClaim;
+  createIlpClient;
+  needsDuplex;
+  constructor(config = {}) {
+    this.fetchImpl = config.fetch ?? fetch;
+    this.resolveClaim = config.resolveClaim;
+    this.createIlpClient = config.createIlpClient ?? ((httpEndpoint) => new HttpIlpClient({ httpEndpoint }));
+    this.needsDuplex = config.needsDuplex ?? false;
+  }
+  /**
+   * `fetch()`-like entry point. Issues the request; on `402` parses the x402
+   * challenge and — when a usable `toon-channel` offer is present and a claim
+   * resolver is configured — pays over TOON and returns the reconstructed
+   * `Response`. Otherwise returns the original 402 unchanged (AC5).
+   */
+  async fetch(url, opts = {}) {
+    const method = (opts.method ?? "GET").toUpperCase();
+    const probe = await this.fetchImpl(url, {
+      method,
+      ...opts.headers ? { headers: opts.headers } : {},
+      ...opts.body !== void 0 ? { body: opts.body } : {},
+      ...opts.timeout !== void 0 ? { signal: AbortSignal.timeout(opts.timeout) } : {}
+    });
+    if (probe.status !== 402) return probe;
+    const challenge = await parseX402Challenge(probe.clone());
+    const accept = challenge.toonChannel;
+    if (!accept || !this.resolveClaim) return probe;
+    return this.payOverToon(url, method, opts, accept, this.resolveClaim);
+  }
+  /**
+   * Open/reuse a channel (via the injected claim resolver), serialize the HTTP
+   * request into the ILP packet `data`, send it to `POST /ilp` with the claim,
+   * and reconstruct the origin `Response` from the FULFILL `data`.
+   */
+  async payOverToon(url, method, opts, accept, resolveClaim) {
+    const destination = opts.destination ?? accept.destination;
+    const claim = await resolveClaim(destination, accept.amount);
+    const requestBytes = serializeHttpRequest({
+      method,
+      url,
+      headers: opts.headers,
+      body: opts.body
+    });
+    const peer = {
+      httpEndpoint: accept.httpEndpoint,
+      supportsUpgrade: accept.supportsUpgrade
+    };
+    const choice = selectIlpTransport(peer, {
+      needsDuplex: this.needsDuplex
+    });
+    const ilpClient = this.createIlpClient(accept.httpEndpoint);
+    const result = await this.sendOverChoice(
+      ilpClient,
+      choice,
+      {
+        destination,
+        amount: String(accept.amount),
+        data: toBase64(requestBytes),
+        ...opts.timeout !== void 0 ? { timeout: opts.timeout } : {}
+      },
+      claim
+    );
+    if (!result.accepted) {
+      throw new ConnectorError(
+        `h402 payment rejected by connector: ${result.code ?? "F00"} ${result.message ?? ""}`.trim()
+      );
+    }
+    if (!result.data) {
+      throw new ConnectorError(
+        "h402 FULFILL carried no data (expected an HTTP response payload)"
+      );
+    }
+    return parseHttpResponse(fromBase64(result.data));
+  }
+  /**
+   * Send the serialized HTTP-in-ILP PREPARE over the selected transport.
+   *
+   * - `http` / `http-upgradable`: stateless one-shot `POST /ilp` with the claim.
+   * - `http-upgradable` additionally exercises {@link HttpIlpClient.upgradeToBtp}
+   *   for the duplex/streaming path (AC4). v1 still drives the actual write over
+   *   the one-shot HTTP method even after upgrading — full duplex body streaming
+   *   is a documented follow-up — but the upgrade call path is wired here.
+   * - `btp`: not reachable from h402 (the x402 offer only carries an
+   *   `httpEndpoint`); guarded for completeness.
+   */
+  async sendOverChoice(ilpClient, choice, params, claim) {
+    if (choice.kind === "http-upgradable") {
+      const btp = await ilpClient.upgradeToBtp();
+      try {
+        return await btp.sendIlpPacketWithClaim(
+          params,
+          claim
+        );
+      } finally {
+        await btp.disconnect().catch(() => {
+        });
+      }
+    }
+    if (choice.kind === "btp") {
+      throw new ToonClientError(
+        "h402 offer resolved to a BTP-only transport; the x402 toon-channel entry must advertise an httpEndpoint",
+        "INVALID_STATE"
+      );
+    }
+    return ilpClient.sendIlpPacketWithClaim(params, claim);
+  }
+};
+function readString(obj, keys) {
+  for (const k of keys) {
+    const v = obj[k];
+    if (typeof v === "string" && v.trim().length > 0) return v.trim();
+  }
+  return void 0;
+}
+function readAmount(obj, keys) {
+  for (const k of keys) {
+    const v = obj[k];
+    if (typeof v === "bigint") return v;
+    if (typeof v === "number" && Number.isFinite(v)) return BigInt(Math.trunc(v));
+    if (typeof v === "string" && /^\d+$/.test(v.trim())) return BigInt(v.trim());
+  }
+  return void 0;
+}
+async function parseX402Challenge(response) {
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return {};
+  }
+  return parseX402Body(body);
+}
+function parseX402Body(body) {
+  if (typeof body !== "object" || body === null) return {};
+  const b = body;
+  const version = typeof b["x402Version"] === "number" ? b["x402Version"] : void 0;
+  const accepts = Array.isArray(b["accepts"]) ? b["accepts"] : [];
+  for (const raw of accepts) {
+    if (typeof raw !== "object" || raw === null) continue;
+    const entry = raw;
+    const scheme = readString(entry, ["scheme"]);
+    if (scheme !== "toon-channel") continue;
+    const destination = readString(entry, [
+      "destination",
+      "ilpAddress",
+      "payTo"
+    ]);
+    const httpEndpoint = readString(entry, [
+      "httpEndpoint",
+      "ilpEndpoint",
+      "endpoint"
+    ]);
+    const amount = readAmount(entry, ["amount", "price", "maxAmountRequired"]);
+    if (!destination || !httpEndpoint || amount === void 0) continue;
+    const network = readString(entry, ["network", "chain"]);
+    const supportsUpgrade = entry["supportsUpgrade"] === true || entry["upgradable"] === true;
+    return {
+      ...version !== void 0 ? { x402Version: version } : {},
+      toonChannel: {
+        scheme: "toon-channel",
+        ...network !== void 0 ? { network } : {},
+        destination,
+        amount,
+        httpEndpoint,
+        supportsUpgrade
+      }
+    };
+  }
+  return version !== void 0 ? { x402Version: version } : {};
+}
+var CRLF = "\r\n";
+function concatHeadAndBody(head, body) {
+  const headBytes = encodeUtf8(head);
+  const out = new Uint8Array(headBytes.length + body.length);
+  out.set(headBytes, 0);
+  out.set(body, headBytes.length);
+  return out;
+}
+function bodyToBytes(body) {
+  if (body === void 0) return new Uint8Array(0);
+  return typeof body === "string" ? encodeUtf8(body) : body;
+}
+function serializeHttpRequest(req) {
+  const u = new URL(req.url);
+  const target = `${u.pathname}${u.search}` || "/";
+  const bodyBytes = bodyToBytes(req.body);
+  const headers = /* @__PURE__ */ new Map();
+  const put = (name, value) => headers.set(name.toLowerCase(), `${name}: ${value}`);
+  const has = (name) => headers.has(name.toLowerCase());
+  for (const [name, value] of Object.entries(req.headers ?? {})) {
+    put(name, value);
+  }
+  if (!has("host")) put("Host", u.host);
+  if (bodyBytes.length > 0 && !has("content-length")) {
+    put("Content-Length", String(bodyBytes.length));
+  }
+  const lines = [
+    `${req.method.toUpperCase()} ${target} HTTP/1.1`,
+    ...headers.values()
+  ];
+  const head = lines.join(CRLF) + CRLF + CRLF;
+  return concatHeadAndBody(head, bodyBytes);
+}
+function findHeaderEnd(bytes) {
+  for (let i = 0; i + 3 < bytes.length; i++) {
+    if (bytes[i] === 13 && bytes[i + 1] === 10 && bytes[i + 2] === 13 && bytes[i + 3] === 10) {
+      return i + 4;
+    }
+  }
+  return -1;
+}
+function parseHttpResponse(bytes) {
+  const headerEnd = findHeaderEnd(bytes);
+  const headBytes = headerEnd === -1 ? bytes : bytes.subarray(0, headerEnd - 2);
+  const body = headerEnd === -1 ? new Uint8Array(0) : bytes.subarray(headerEnd);
+  const headText = decodeUtf8(headBytes);
+  const lines = headText.split(CRLF).filter((l) => l.length > 0);
+  const statusLine = lines.shift();
+  if (!statusLine) {
+    throw new ConnectorError(
+      "h402 response payload had no HTTP status line"
+    );
+  }
+  const match = /^HTTP\/\d\.\d\s+(\d{3})(?:\s+(.*))?$/.exec(statusLine.trim());
+  if (!match) {
+    throw new ConnectorError(
+      `h402 response payload had a malformed status line: "${statusLine}"`
+    );
+  }
+  const status = parseInt(match[1], 10);
+  const statusText = match[2] ?? "";
+  const headers = new Headers();
+  for (const line of lines) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const name = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim();
+    if (name.length === 0) continue;
+    headers.append(name, value);
+  }
+  const nullBodyStatus = status === 101 || status === 204 || status === 205 || status === 304;
+  const init = { status, headers };
+  if (statusText) init.statusText = statusText;
+  return new Response(
+    nullBodyStatus || body.length === 0 ? null : body.slice(),
+    init
+  );
+}
+
 // src/ToonClient.ts
 var ToonClient = class {
   config;
@@ -3355,6 +3919,28 @@ var ToonClient = class {
   getPublicKey() {
     return getPublicKey2(this.config.secretKey);
   }
+  /**
+   * Sign an unsigned Nostr event template with the client's Nostr secret key,
+   * returning a fully-signed event (id + pubkey + sig).
+   *
+   * This is the key primitive behind the daemon's sign-and-publish path: a UI
+   * or agent supplies only `{ kind, content, tags, created_at }` and never holds
+   * the private key — signing happens here, inside the key owner.
+   */
+  signEvent(template) {
+    return finalizeEvent(template, this.config.secretKey);
+  }
+  /**
+   * Upload bytes to Arweave via the kind:5094 blob-storage DVM (single-packet),
+   * signing the request with this client's Nostr key and paying through its
+   * existing channel. Returns the Arweave tx id on success.
+   *
+   * Backs the daemon's `upload-media` path: the key and claim/channel plumbing
+   * stay inside the client; callers pass only the bytes.
+   */
+  async uploadBlob(params) {
+    return requestBlobStorage(this, this.config.secretKey, params);
+  }
   /**
    * Per-chain settlement readiness for the configured `network` tier, mirroring
    * the townhouse node's status. Returns `undefined` when no named `network` is
@@ -3637,6 +4223,46 @@ var ToonClient = class {
       );
     }
   }
+  /**
+   * Payment-aware HTTP fetch over TOON (issue #50). A `fetch()`-like method that
+   * makes paying for an HTTP resource transparent:
+   *
+   *   1. Issues the HTTP request to `url`.
+   *   2. On `402`, parses the x402 `accepts` array and selects the
+   *      `toon-channel` entry (see {@link Http402Client} for the wire shape).
+   *   3. Opens/reuses a payment channel for the entry's ILP destination (via
+   *      ChannelManager), signs a balance proof for the demanded price, and
+   *      re-sends the SAME HTTP request as a transparent HTTP-in-ILP packet to
+   *      the connector's `POST /ilp` (via {@link HttpIlpClient}), with the claim
+   *      in the `ILP-Payment-Channel-Claim` header.
+   *   4. Reconstructs and returns a standard Web `Response` from the FULFILL
+   *      `data`. The caller never sees ILP.
+   *
+   * If the origin offers no `toon-channel` entry, the original `402` Response is
+   * returned unchanged (the caller sees the vanilla x402 challenge).
+   *
+   * The channel/claim plumbing is wired to the live ChannelManager + per-chain
+   * signer via `resolveClaimForDestination` — identical to `publishEvent`. The
+   * `amount` paid comes from the selected x402 entry (the resource's price).
+   *
+   * @throws {ToonClientError} If the client is not started.
+   * @throws {ConnectorError} If the connector rejects the payment or returns no
+   *   HTTP payload.
+   */
+  async h402Fetch(url, opts) {
+    if (!this.state) {
+      throw new ToonClientError(
+        "Client not started. Call start() first.",
+        "INVALID_STATE"
+      );
+    }
+    const client = new Http402Client({
+      ...this.channelManager ? {
+        resolveClaim: (destination, amount) => this.resolveClaimForDestination(destination, amount)
+      } : {}
+    });
+    return client.fetch(url, opts);
+  }
   /**
    * Sends a raw swap ILP packet (Story 12.5) to a Mill peer with an attached
    * balance-proof claim. This is a lower-level surface than `publishEvent`:
@@ -4735,74 +5361,8 @@ function buildPetPurchaseRequest(params) {
   };
 }
 
-// src/blob-storage.ts
-import { buildBlobStorageRequest } from "@toon-protocol/core";
-var ARWEAVE_TX_ID_REGEX = /^[A-Za-z0-9_-]{43}$/;
-async function requestBlobStorage(client, secretKey, params) {
-  const bid = params.bid ?? (params.ilpAmount !== void 0 ? String(params.ilpAmount) : void 0);
-  if (bid === void 0 || bid === "") {
-    return {
-      success: false,
-      error: "requestBlobStorage requires a bid (or ilpAmount to derive it)"
-    };
-  }
-  const blobBuffer = Buffer.from(
-    params.blobData.buffer,
-    params.blobData.byteOffset,
-    params.blobData.byteLength
-  );
-  let event;
-  try {
-    event = buildBlobStorageRequest(
-      {
-        blobData: blobBuffer,
-        contentType: params.contentType,
-        bid
-      },
-      secretKey
-    );
-  } catch (error) {
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : String(error)
-    };
-  }
-  const result = await client.publishEvent(event, {
-    destination: params.destination,
-    claim: params.claim,
-    ilpAmount: params.ilpAmount
-  });
-  if (!result.success) {
-    return {
-      success: false,
-      eventId: result.eventId ?? event.id,
-      error: result.error ?? "Blob storage request rejected"
-    };
-  }
-  if (!result.data) {
-    return {
-      success: false,
-      eventId: event.id,
-      error: "FULFILL contained no data; expected base64-encoded Arweave tx ID"
-    };
-  }
-  const txId = decodeUtf8(fromBase64(result.data));
-  if (!ARWEAVE_TX_ID_REGEX.test(txId)) {
-    return {
-      success: false,
-      eventId: event.id,
-      error: `Decoded FULFILL data is not a valid Arweave tx ID: "${txId}"`
-    };
-  }
-  return {
-    success: true,
-    txId,
-    eventId: event.id
-  };
-}
-
 // src/keys/KeyManager.ts
-import { finalizeEvent } from "nostr-tools/pure";
+import { finalizeEvent as finalizeEvent2 } from "nostr-tools/pure";
 import { nip19 } from "nostr-tools";
 
 // src/keys/PasskeyAuth.ts
@@ -5588,7 +6148,7 @@ var KeyManager = class {
       this.vault,
       this.identity.nostr.secretKey
     );
-    const signedEvent = finalizeEvent(
+    const signedEvent = finalizeEvent2(
       eventTemplate,
       this.identity.nostr.secretKey
     );
@@ -5849,8 +6409,13 @@ export {
   EvmSigner,
   HS_HOSTNAME_MAX_LENGTH,
   HS_HOSTNAME_REGEX,
+  Http402Client,
   HttpConnectorAdmin,
+  HttpIlpClient,
   HttpRuntimeClient,
+  ILP_CLAIM_HEADER,
+  ILP_CLAIM_WRAPPED_HEADER,
+  ILP_PEER_ID_HEADER,
   KeyManager,
   MinaSigner,
   NetworkError,
@@ -5879,17 +6444,24 @@ export {
   generateMnemonic,
   generateRandomIdentity,
   getNetworkStatus,
+  httpEndpointToBtpUrl,
   importKeystore,
   isPrfSupported,
   isRoutableHsHostname,
   loadKeystore,
   parseBackupPayload,
+  parseHttpResponse,
   parsePetInteractionEvent,
   parsePetInteractionResult,
   parsePetListing,
+  parseX402Body,
+  parseX402Challenge,
+  readDiscoveredIlpPeer,
   readMinaDepositTotal,
   requestBlobStorage,
   selectAnonAsset,
+  selectIlpTransport,
+  serializeHttpRequest,
   startManagedAnonProxy,
   validateConfig,
   validateMnemonic,