@toon-protocol/client 0.9.2 → 0.11.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _toon_protocol_core from '@toon-protocol/core';
-import { IlpPeerInfo, NetworkFamilyStatus, IlpSendResult, IlpClient, ConnectorAdminClient, ConnectorChannelClient, OpenChannelParams, OpenChannelResult, ChannelState } from '@toon-protocol/core';
-import { NostrEvent } from 'nostr-tools/pure';
+import { IlpPeerInfo, IlpClient, IlpSendResult, NetworkFamilyStatus, ConnectorAdminClient, ConnectorChannelClient, OpenChannelParams, OpenChannelResult, ChannelState } from '@toon-protocol/core';
+import { NostrEvent, EventTemplate } from 'nostr-tools/pure';
 import { PrivateKeyAccount } from 'viem/accounts';
 
 /**
@@ -199,6 +199,27 @@ interface ToonClientConfig {
     btpAuthToken?: string;
     /** Peer ID for BTP connection (used in connector env var BTP_PEER_{ID}_SECRET) */
     btpPeerId?: string;
+    /**
+     * ILP-over-HTTP one-shot endpoint of the uplink connector (the `POST /ilp`
+     * URL, e.g. "http://localhost:3000/ilp"). When set, the client prefers the
+     * stateless {@link HttpIlpClient} transport for one-shot writes instead of
+     * opening a persistent BTP WebSocket.
+     *
+     * This mirrors the `httpEndpoint` field a peer advertises in discovery
+     * (`IlpPeerInfo`, toon PR #29). It is surfaced here as explicit config so the
+     * default runtime can opt into ILP-over-HTTP before connectors advertise the
+     * field on-wire. Leave unset to keep the existing BTP-only behavior (the safe
+     * default — no connector advertises an httpEndpoint until the connector + a
+     * core release with these fields ship).
+     */
+    connectorHttpEndpoint?: string;
+    /**
+     * Whether the uplink connector accepts a BTP `Upgrade` over its HTTP endpoint
+     * (mirrors `IlpPeerInfo.supportsUpgrade`, toon PR #29). Only consulted when
+     * `connectorHttpEndpoint` is set and a duplex session is required. Defaults to
+     * false (no upgrade) when omitted.
+     */
+    connectorSupportsUpgrade?: boolean;
     /**
      * ILP destination address for event publishing.
      * Defaults to the connector's local address (derived from connectorUrl host).
@@ -391,6 +412,514 @@ type ClientTransportConfig = {
     gatewayUrl: string;
 };
 
+/**
+ * Client-side helper for kind:5094 Arweave blob storage DVM requests.
+ *
+ * This composes the three steps a caller previously had to wire by hand:
+ *   1. Build the kind:5094 event via `buildBlobStorageRequest()` (@toon-protocol/core).
+ *   2. Publish it to the DVM destination over ILP via `ToonClient.publishEvent()`
+ *      (reusing the existing claim / channel plumbing).
+ *   3. Decode the FULFILL `data` field into the Arweave transaction ID.
+ *
+ * ## FULFILL data contract
+ *
+ * For a successful single-packet (non-chunked) blob upload, the DVM provider
+ * returns the Arweave transaction ID as a **UTF-8 string, base64-encoded** in
+ * the ILP FULFILL `data` field (the connector validates that FULFILL data is
+ * base64). An Arweave tx ID is a 43-character base64url string (32 raw bytes).
+ *
+ * So the decode is:
+ *   `txId = utf8(base64decode(result.data))`
+ *
+ * See `packages/sdk/src/arweave/arweave-dvm-handler.ts` for the server side and
+ * `packages/client/tests/e2e/docker-arweave-dvm-e2e.test.ts` for the reference
+ * end-to-end flow this helper mirrors.
+ *
+ * Chunked uploads (multi-packet, via `uploadId` / `chunkIndex` / `totalChunks`
+ * params) are intentionally out of scope for this single-packet helper — the
+ * provider returns `ack:<n>` for intermediate chunks and the tx ID only on the
+ * final chunk. Callers needing chunking should drive `publishEvent()` directly
+ * (see the chunked case in the reference E2E test). Tracked as a follow-up.
+ */
+
+/**
+ * Parameters for {@link requestBlobStorage}.
+ */
+interface RequestBlobStorageParams {
+    /** The raw blob data to store on Arweave. */
+    blobData: Uint8Array;
+    /**
+     * MIME type of the blob. Defaults to `'application/octet-stream'`
+     * (matching `buildBlobStorageRequest`).
+     */
+    contentType?: string;
+    /**
+     * Bid amount in USDC micro-units, as a string (declared in the event's
+     * `bid` tag). Defaults to the stringified `ilpAmount` when omitted.
+     *
+     * At least one of `bid` / `ilpAmount` should be provided so the declared
+     * bid and the paid ILP amount agree.
+     */
+    bid?: string;
+    /**
+     * ILP destination address of the DVM that performs the upload
+     * (e.g. `'g.toon.peer1'`). Falls back to the client's configured
+     * `destinationAddress` when omitted.
+     */
+    destination?: string;
+    /**
+     * Pre-signed balance proof claim for this packet. When omitted, the
+     * client's channel manager auto-opens a channel and auto-signs a claim
+     * (same lazy-channel behavior as `publishEvent`).
+     */
+    claim?: SignedBalanceProof;
+    /**
+     * Explicit ILP payment amount (bigint micro-units). When omitted,
+     * `publishEvent` computes it from the encoded event size. When `bid`
+     * is omitted, this value is stringified to populate the event's bid tag.
+     */
+    ilpAmount?: bigint;
+}
+/**
+ * Typed result of {@link requestBlobStorage}.
+ */
+interface RequestBlobStorageResult {
+    /** Whether the upload succeeded and a tx ID was decoded. */
+    success: boolean;
+    /** The Arweave transaction ID (43-char base64url) when `success` is true. */
+    txId?: string;
+    /** The id of the kind:5094 event that was published. */
+    eventId?: string;
+    /** Error message when `success` is false. */
+    error?: string;
+}
+/**
+ * Requests permanent Arweave blob storage from a DVM in a single ILP packet.
+ *
+ * Mirrors the single-packet flow in
+ * `packages/client/tests/e2e/docker-arweave-dvm-e2e.test.ts`: builds a signed
+ * kind:5094 event, publishes it through the supplied {@link ToonClient}
+ * (reusing its claim/channel plumbing), and decodes the FULFILL `data` field
+ * into an Arweave transaction ID.
+ *
+ * @param client - A started `ToonClient` (call `client.start()` first).
+ * @param secretKey - The Nostr secret key used to sign the kind:5094 event.
+ * @param params - Blob, content type, bid, destination, and payment options.
+ * @returns `{ success, txId?, eventId?, error? }`.
+ */
+declare function requestBlobStorage(client: ToonClient, secretKey: Uint8Array, params: RequestBlobStorageParams): Promise<RequestBlobStorageResult>;
+
+interface BtpRuntimeClientConfig {
+    btpUrl: string;
+    peerId: string;
+    authToken: string;
+    /** Max reconnection attempts on send failure (default: 3) */
+    maxRetries?: number;
+    /** Delay between reconnection attempts in ms (default: 1000) */
+    retryDelay?: number;
+    /** Custom WebSocket constructor (for SOCKS5 proxy support). */
+    createWebSocket?: (url: string) => WebSocket;
+}
+/**
+ * BTP transport implementing IlpClient.
+ * Uses IsomorphicBtpClient (browser-native, no Node.js dependencies).
+ */
+declare class BtpRuntimeClient implements IlpClient {
+    private btpClient;
+    private readonly config;
+    private _isConnected;
+    constructor(config: BtpRuntimeClientConfig);
+    /**
+     * Connects to the BTP peer via WebSocket.
+     */
+    connect(): Promise<void>;
+    /**
+     * Attempts to reconnect by creating a fresh client and connecting.
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Disconnects from the BTP peer.
+     */
+    disconnect(): Promise<void>;
+    get isConnected(): boolean;
+    /**
+     * Sends an ILP packet via BTP with auto-reconnect on connection errors.
+     * Satisfies IlpClient interface.
+     */
+    sendIlpPacket(params: {
+        destination: string;
+        amount: string;
+        data: string;
+        timeout?: number;
+    }): Promise<IlpSendResult>;
+    /**
+     * Sends a balance proof claim via BTP protocol data, then sends an ILP packet.
+     * Auto-reconnects on connection errors.
+     */
+    sendIlpPacketWithClaim(params: {
+        destination: string;
+        amount: string;
+        data: string;
+        timeout?: number;
+    }, claim: Record<string, unknown>): Promise<IlpSendResult>;
+    /**
+     * Send a standalone `payment-channel-claim` BTP MESSAGE (no ILP packet
+     * attached). The connector's ClaimReceiver consumes this fire-and-forget
+     * to register cumulative claim state independently of the per-packet
+     * forwarding path. Auto-reconnects on connection errors.
+     */
+    sendClaimMessage(claim: Record<string, unknown>): Promise<void>;
+    private _sendClaimMessageOnce;
+    /**
+     * Single-attempt ILP packet send. Reconnects if not connected.
+     */
+    private _sendIlpPacketOnce;
+    /**
+     * Single-attempt claim + ILP packet send. Reconnects if not connected.
+     */
+    private _sendIlpPacketWithClaimOnce;
+}
+
+/**
+ * ILP-over-HTTP (RFC-0035) transport for the TOON client.
+ *
+ * The connector now serves ILP-over-HTTP on the SAME port as BTP (connector
+ * PR #181). This adapter lets a client do stateless one-shot writes over HTTP
+ * (`POST /ilp`) and upgrade to a duplex BTP session when it needs to receive
+ * server-initiated packets or act as a peer.
+ *
+ * Wire contract (targets connector PR #181's `/ilp`):
+ *  - One-shot write: `POST /ilp`
+ *      body:    OER-encoded ILP PREPARE (`application/octet-stream`)
+ *      header:  `ILP-Payment-Channel-Claim: base64(JSON of the claim)` — the
+ *               SAME claim JSON the BTP path attaches as the
+ *               `payment-channel-claim` protocolData entry.
+ *      optional: `ILP-Peer-Id` + `Authorization: Bearer <secret>` identity.
+ *      response: `200 OK` with an OER FULFILL or REJECT body. HTTP non-2xx is
+ *                reserved for TRANSPORT errors (400/401/413/5xx); ILP-level
+ *                rejects come back as a 200 + REJECT body.
+ *  - Upgrade to BTP: standard HTTP `Upgrade` with `Sec-WebSocket-Protocol: btp`
+ *      plus the same `ILP-Peer-Id` + `Authorization` headers. The connector
+ *      pre-authenticates the BTP session from those headers (continuity), so
+ *      after `101` we send BTP frames WITHOUT a separate in-band auth frame.
+ *      Omitting the auth headers falls back to the normal BTP auth-frame flow.
+ *
+ * Reuses `serializeIlpPrepare`/`deserializeIlpPacket` from `btp/protocol.ts` —
+ * the SAME OER codec the BTP path uses. Claim signing/construction is owned by
+ * the caller (BootstrapService); this transport never builds or signs claims.
+ */
+
+/** Header carrying the base64(JSON) payment-channel claim. */
+declare const ILP_CLAIM_HEADER = "ILP-Payment-Channel-Claim";
+/** Header carrying a NIP-59 wrapped (gift-wrapped) claim. */
+declare const ILP_CLAIM_WRAPPED_HEADER = "ILP-Payment-Channel-Claim-Wrapped";
+/** Header carrying the peer identity. */
+declare const ILP_PEER_ID_HEADER = "ILP-Peer-Id";
+interface HttpIlpClientConfig {
+    /** The peer's `POST /ilp` URL (the `httpEndpoint` from discovery). */
+    httpEndpoint: string;
+    /**
+     * Optional peer identity. With no `peerId`/`authToken` the connector treats
+     * the request as an anonymous no-auth peer (permissionless default) and
+     * derives an ephemeral id from the claim signer.
+     */
+    peerId?: string;
+    /** Bearer secret for `Authorization`. Omit for the no-auth peer path. */
+    authToken?: string;
+    /** Request timeout in milliseconds (default: 30000). */
+    timeout?: number;
+    /** Max retry attempts for transport-level network failures (default: 3). */
+    maxRetries?: number;
+    /** Initial retry delay in milliseconds (default: 1000). */
+    retryDelay?: number;
+    /** Custom fetch implementation (SOCKS5 mode / testing). */
+    httpClient?: typeof fetch;
+    /**
+     * Custom WebSocket constructor for the BTP upgrade path (SOCKS5 mode).
+     * Forwarded to the underlying BtpRuntimeClient.
+     */
+    createWebSocket?: (url: string) => WebSocket;
+}
+/**
+ * Stateless ILP-over-HTTP transport implementing `IlpClient`.
+ *
+ * Use this for pure one-shot consumers (publish-and-forget writes). When the
+ * client needs a duplex session — to receive server-initiated packets or to act
+ * as a peer — call {@link upgradeToBtp} to obtain a connected BtpRuntimeClient
+ * that reuses the existing BTP code path.
+ */
+declare class HttpIlpClient implements IlpClient {
+    private readonly httpEndpoint;
+    private readonly peerId;
+    private readonly authToken;
+    private readonly timeout;
+    private readonly retryConfig;
+    private readonly httpClient;
+    private readonly createWebSocket;
+    constructor(config: HttpIlpClientConfig);
+    /**
+     * 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.
+     */
+    sendIlpPacket(params: {
+        destination: string;
+        amount: string;
+        data: string;
+        timeout?: number;
+    }): Promise<IlpSendResult>;
+    /**
+     * 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.
+     */
+    sendIlpPacketWithClaim(params: {
+        destination: string;
+        amount: string;
+        data: string;
+        timeout?: number;
+    }, claim: unknown): Promise<IlpSendResult>;
+    /**
+     * 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.
+     */
+    upgradeToBtp(): Promise<BtpRuntimeClient>;
+    private authHeaders;
+    /**
+     * 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).
+     */
+    private postPrepare;
+    /**
+     * 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.
+     */
+    private mapResponse;
+    private mapTransportError;
+}
+/**
+ * Derive the BTP WebSocket URL from a `POST /ilp` HTTP endpoint. The connector
+ * serves BTP on the SAME path, so we only swap the scheme (http→ws, https→wss).
+ */
+declare function httpEndpointToBtpUrl(httpEndpoint: string): string;
+
+/**
+ * Payment-aware HTTP fetch over TOON (the "h402" flow).
+ *
+ * This adapter makes paying for an HTTP resource transparent: it issues an
+ * ordinary HTTP request, and when the origin answers `402 Payment Required`
+ * with an x402-style challenge that offers a `toon-channel` payment option, it
+ * opens/reuses a payment channel, signs a balance-proof claim, and re-sends the
+ * SAME HTTP request as a "transparent HTTP-in-ILP" packet to the connector's
+ * `POST /ilp` endpoint (via {@link HttpIlpClient}). The connector terminates the
+ * payment, forwards the request to the origin, and returns the origin's HTTP
+ * response inside the ILP FULFILL `data`. We reconstruct a normal Web `Response`
+ * from those bytes — the caller never sees ILP.
+ *
+ * ─── x402 wire contract (the 402 challenge body) ────────────────────────────
+ * The connector side (the 402 greeting + the `accepts` entries) is a separate,
+ * NOT-YET-BUILT dependency, so we parse DEFENSIVELY (mirroring
+ * `readDiscoveredIlpPeer` in selectIlpTransport.ts): a slightly different
+ * connector shape should degrade gracefully (fall back to the vanilla 402)
+ * rather than throw.
+ *
+ * Expected 402 JSON body (x402 v1-ish):
+ * ```jsonc
+ * {
+ *   "x402Version": 1,
+ *   "accepts": [
+ *     {
+ *       "scheme": "toon-channel",      // REQUIRED — selects the TOON option.
+ *       "network": "evm:base:8453",    // optional — chain key (informational).
+ *       "destination": "g.toon.apex",  // ILP destination address to pay (the
+ *                                      //   connector route that fronts the URL).
+ *       "amount": "1000",              // price in ILP base units (string|number).
+ *       "httpEndpoint": "https://apex/ilp", // the connector's POST /ilp URL.
+ *       "supportsUpgrade": true        // optional — host accepts the BTP upgrade.
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * Field aliases read defensively (first present wins):
+ *   - destination: `destination` | `ilpAddress` | `payTo` | `maxAmountRequired`'s
+ *     sibling `payTo`. (We do NOT invent a value — a missing destination makes
+ *     the entry unusable and we fall back to the vanilla 402.)
+ *   - amount:      `amount` | `price` | `maxAmountRequired`.
+ *   - httpEndpoint:`httpEndpoint` | `ilpEndpoint` | `endpoint`.
+ *   - upgrade:     `supportsUpgrade` | `upgradable`.
+ *
+ * ─── HTTP-in-ILP framing ────────────────────────────────────────────────────
+ * The raw HTTP request/response is serialized as minimal HTTP/1.1 wire bytes
+ * (request-line / status-line + headers + CRLFCRLF + body) and carried as the
+ * ILP packet `data` (base64). See {@link serializeHttpRequest} /
+ * {@link parseHttpResponse}. This keeps the connector free to forward the bytes
+ * verbatim and lets us rebuild a standard `Response`.
+ *
+ * Claim signing/construction is owned by the CALLER (ToonClient wires the live
+ * ChannelManager + signer). This adapter never builds or validates claims —
+ * payment-claim validation lives ONLY in the connector.
+ */
+
+/** A single parsed `accepts` entry that offers the `toon-channel` scheme. */
+interface ToonChannelAccept {
+    /** Always `'toon-channel'` for a matched entry. */
+    scheme: 'toon-channel';
+    /** Optional chain key, e.g. `evm:base:8453` — informational. */
+    network?: string;
+    /** ILP destination address to pay (the connector route fronting the URL). */
+    destination: string;
+    /** Price in ILP base units. */
+    amount: bigint;
+    /** The connector's `POST /ilp` URL. */
+    httpEndpoint: string;
+    /** Whether the host accepts the BTP upgrade over the HTTP endpoint. */
+    supportsUpgrade: boolean;
+}
+/** The parsed x402 402 body, with the selected `toon-channel` entry (if any). */
+interface ParsedX402Challenge {
+    x402Version?: number;
+    /** The first usable `toon-channel` accepts entry, or `undefined`. */
+    toonChannel?: ToonChannelAccept;
+}
+/** Options for {@link Http402Client.fetch} / `ToonClient.h402Fetch`. */
+interface H402FetchOptions {
+    /** HTTP method. Default `'GET'`. */
+    method?: string;
+    /** Request headers. */
+    headers?: Record<string, string>;
+    /** Request body. */
+    body?: string | Uint8Array;
+    /** Request timeout in milliseconds. */
+    timeout?: number;
+    /** Optional explicit ILP destination override (else the x402 entry's value). */
+    destination?: string;
+}
+/**
+ * Caller-supplied hook that signs a balance-proof claim for `(destination,
+ * amount)` and returns the chain-appropriate claim message to attach to the ILP
+ * PREPARE. ToonClient wires this to its ChannelManager + per-chain signer (the
+ * exact same plumbing as `publishEvent`). The returned value is forwarded
+ * opaquely as the `ILP-Payment-Channel-Claim` header by {@link HttpIlpClient}.
+ */
+type ClaimResolver = (destination: string, amount: bigint) => Promise<unknown>;
+/** Factory for an {@link HttpIlpClient} given a resolved `POST /ilp` endpoint. */
+type HttpIlpClientFactory = (httpEndpoint: string) => HttpIlpClient;
+interface Http402ClientConfig {
+    /**
+     * Underlying HTTP fetch for the INITIAL (un-paid) request that probes for a
+     * 402. Default: global `fetch`.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Resolves + signs the payment-channel claim. REQUIRED to pay; if omitted,
+     * a 402 with a `toon-channel` offer is surfaced unchanged (vanilla challenge).
+     */
+    resolveClaim?: ClaimResolver;
+    /**
+     * Builds the {@link HttpIlpClient} for a resolved endpoint. Default: construct
+     * a new `HttpIlpClient({ httpEndpoint })`. Injectable for tests / SOCKS5.
+     */
+    createIlpClient?: HttpIlpClientFactory;
+    /**
+     * AC4: request a duplex transport for the paid send. When `true` and the
+     * toon-channel entry advertises `supportsUpgrade`, {@link selectIlpTransport}
+     * returns `http-upgradable` and the send path calls
+     * {@link HttpIlpClient.upgradeToBtp} before writing — the wiring for
+     * large/streaming responses. Default `false` (stateless one-shot HTTP).
+     *
+     * NOTE (v1 limitation): even on the upgrade path the actual write is still a
+     * one-shot `sendIlpPacketWithClaim`; full duplex body streaming over the BTP
+     * session is a documented follow-up. The selection + upgrade CALL PATH is
+     * wired and exercised here so the streaming consumer can take over the
+     * returned session in a later iteration.
+     */
+    needsDuplex?: boolean;
+}
+/**
+ * Reusable h402 fetch engine. `ToonClient.h402Fetch` is a thin wrapper that
+ * constructs this with the live claim/channel plumbing.
+ */
+declare class Http402Client {
+    private readonly fetchImpl;
+    private readonly resolveClaim?;
+    private readonly createIlpClient;
+    private readonly needsDuplex;
+    constructor(config?: Http402ClientConfig);
+    /**
+     * `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).
+     */
+    fetch(url: string, opts?: H402FetchOptions): Promise<Response>;
+    /**
+     * 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`.
+     */
+    private payOverToon;
+    /**
+     * 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.
+     */
+    private sendOverChoice;
+}
+/**
+ * Parse a 402 `Response` body into a {@link ParsedX402Challenge}, selecting the
+ * first usable `toon-channel` entry. Reads every field defensively; a malformed
+ * body, a non-JSON body, or an entry missing its `destination`/`httpEndpoint`
+ * yields `{ toonChannel: undefined }` so the caller falls back to the vanilla
+ * 402 rather than throwing.
+ */
+declare function parseX402Challenge(response: Response): Promise<ParsedX402Challenge>;
+/** Pure parser over an already-decoded x402 body (testable without a Response). */
+declare function parseX402Body(body: unknown): ParsedX402Challenge;
+/**
+ * Serialize a raw HTTP request to HTTP/1.1 wire bytes:
+ * `METHOD path HTTP/1.1\r\n` + `Host:` + headers + `\r\n\r\n` + body.
+ *
+ * The request-line target is the URL's path+query (origin-form); we add a
+ * `Host` header from the URL authority and a `Content-Length` when there's a
+ * body, unless the caller already supplied them. Header names are matched
+ * case-insensitively so we never duplicate `Host`/`Content-Length`.
+ */
+declare function serializeHttpRequest(req: {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array;
+}): Uint8Array;
+/**
+ * Parse HTTP/1.1 wire bytes (status-line + headers + CRLFCRLF + body) into a
+ * standard Web `Response`. Used to reconstruct the origin response from the ILP
+ * FULFILL `data`.
+ *
+ * @throws {ConnectorError} If the bytes are not a parseable HTTP/1.1 response.
+ */
+declare function parseHttpResponse(bytes: Uint8Array): Response;
+
 /**
  * ToonClient - High-level client for interacting with TOON network.
  *
@@ -469,6 +998,30 @@ declare class ToonClient {
      * Works before start() is called.
      */
     getPublicKey(): string;
+    /**
+     * 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: EventTemplate): NostrEvent;
+    /**
+     * 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.
+     */
+    uploadBlob(params: {
+        blobData: Uint8Array;
+        contentType?: string;
+        bid?: string;
+        destination?: string;
+        ilpAmount?: bigint;
+    }): Promise<RequestBlobStorageResult>;
     /**
      * Per-chain settlement readiness for the configured `network` tier, mirroring
      * the townhouse node's status. Returns `undefined` when no named `network` is
@@ -526,6 +1079,33 @@ declare class ToonClient {
         claim?: SignedBalanceProof;
         ilpAmount?: bigint;
     }): Promise<PublishEventResult>;
+    /**
+     * 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.
+     */
+    h402Fetch(url: string, opts?: H402FetchOptions): Promise<Response>;
     /**
      * 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`:
@@ -1041,76 +1621,78 @@ declare class HttpConnectorAdmin implements ConnectorAdminClient {
     private handleErrorResponse;
 }
 
-interface BtpRuntimeClientConfig {
-    btpUrl: string;
-    peerId: string;
-    authToken: string;
-    /** Max reconnection attempts on send failure (default: 3) */
-    maxRetries?: number;
-    /** Delay between reconnection attempts in ms (default: 1000) */
-    retryDelay?: number;
-    /** Custom WebSocket constructor (for SOCKS5 proxy support). */
-    createWebSocket?: (url: string) => WebSocket;
-}
 /**
- * BTP transport implementing IlpClient.
- * Uses IsomorphicBtpClient (browser-native, no Node.js dependencies).
- */
-declare class BtpRuntimeClient implements IlpClient {
-    private btpClient;
-    private readonly config;
-    private _isConnected;
-    constructor(config: BtpRuntimeClientConfig);
-    /**
-     * Connects to the BTP peer via WebSocket.
-     */
-    connect(): Promise<void>;
-    /**
-     * Attempts to reconnect by creating a fresh client and connecting.
-     */
-    reconnect(): Promise<void>;
-    /**
-     * Disconnects from the BTP peer.
-     */
-    disconnect(): Promise<void>;
-    get isConnected(): boolean;
-    /**
-     * Sends an ILP packet via BTP with auto-reconnect on connection errors.
-     * Satisfies IlpClient interface.
-     */
-    sendIlpPacket(params: {
-        destination: string;
-        amount: string;
-        data: string;
-        timeout?: number;
-    }): Promise<IlpSendResult>;
-    /**
-     * Sends a balance proof claim via BTP protocol data, then sends an ILP packet.
-     * Auto-reconnects on connection errors.
-     */
-    sendIlpPacketWithClaim(params: {
-        destination: string;
-        amount: string;
-        data: string;
-        timeout?: number;
-    }, claim: Record<string, unknown>): Promise<IlpSendResult>;
-    /**
-     * Send a standalone `payment-channel-claim` BTP MESSAGE (no ILP packet
-     * attached). The connector's ClaimReceiver consumes this fire-and-forget
-     * to register cumulative claim state independently of the per-packet
-     * forwarding path. Auto-reconnects on connection errors.
-     */
-    sendClaimMessage(claim: Record<string, unknown>): Promise<void>;
-    private _sendClaimMessageOnce;
-    /**
-     * Single-attempt ILP packet send. Reconnects if not connected.
-     */
-    private _sendIlpPacketOnce;
+ * Transport selection policy for the client ILP layer.
+ *
+ * The connector serves ILP-over-HTTP (`POST /ilp`) and BTP on the SAME port
+ * (connector PR #181). A peer advertises this in discovery via the toon-core
+ * `IlpPeerInfo` fields added in toon PR #29:
+ *   - `httpEndpoint?: string`   — the `POST /ilp` URL.
+ *   - `supportsUpgrade?: boolean` — whether the host accepts the BTP upgrade.
+ *
+ * Those fields may not yet exist on the installed `@toon-protocol/core`
+ * `IlpPeerInfo` type, so we read them defensively here (see `DiscoveredIlpPeer`).
+ *
+ * Policy:
+ *   - Pure one-shot consumers (`needsDuplex: false`) prefer HTTP when the peer
+ *     advertises an `httpEndpoint` — stateless, no persistent socket.
+ *   - Clients that must receive server-initiated packets or act as a peer
+ *     (`needsDuplex: true`) use BTP. If the peer only exposes `httpEndpoint`
+ *     and `supportsUpgrade` is true, we go HTTP-then-upgrade; otherwise we
+ *     connect to the BTP endpoint directly.
+ */
+/**
+ * The subset of discovery fields this policy reads. Structurally compatible with
+ * core's `IlpPeerInfo`; `httpEndpoint`/`supportsUpgrade` are optional so a
+ * pre-PR-#29 `IlpPeerInfo` can be passed through a cast.
+ */
+interface DiscoveredIlpPeer {
+    /** BTP WebSocket endpoint (always present on a TOON peer). */
+    btpEndpoint?: string;
+    /** `POST /ilp` URL (toon PR #29). */
+    httpEndpoint?: string;
+    /** Whether the host accepts the BTP upgrade over the HTTP endpoint (toon PR #29). */
+    supportsUpgrade?: boolean;
+}
+type IlpTransportChoice = 
+/** Stateless one-shot writes via `POST /ilp`. */
+{
+    kind: 'http';
+    httpEndpoint: string;
+    canUpgrade: boolean;
+}
+/** Duplex BTP session via the WebSocket endpoint. */
+ | {
+    kind: 'btp';
+    btpEndpoint: string;
+}
+/**
+ * Open HTTP first (one-shot writes) but upgrade to BTP when duplex is needed.
+ * Only chosen when the peer exposes `httpEndpoint` + `supportsUpgrade` and no
+ * separate `btpEndpoint`.
+ */
+ | {
+    kind: 'http-upgradable';
+    httpEndpoint: string;
+};
+interface SelectIlpTransportOptions {
     /**
-     * Single-attempt claim + ILP packet send. Reconnects if not connected.
+     * Whether the client needs a duplex session (receive server-initiated
+     * packets / act as a peer). Default: false (pure one-shot consumer).
      */
-    private _sendIlpPacketWithClaimOnce;
+    needsDuplex?: boolean;
 }
+/**
+ * Read discovery fields defensively from a (possibly pre-PR-#29) peer info
+ * object. Accepts core's `IlpPeerInfo` or any structurally-compatible shape.
+ */
+declare function readDiscoveredIlpPeer(peer: unknown): DiscoveredIlpPeer;
+/**
+ * Choose the ILP transport for a discovered peer given the consumer's needs.
+ *
+ * @throws {Error} If the peer advertises no usable endpoint at all.
+ */
+declare function selectIlpTransport(peer: DiscoveredIlpPeer, options?: SelectIlpTransportOptions): IlpTransportChoice;
 
 /**
  * Chain-specific metadata (discriminated union).
@@ -1918,7 +2500,7 @@ declare function validateConfig(config: ToonClientConfig): void;
  * The resolved config type after defaults are applied.
  * secretKey is guaranteed to be present (auto-generated if omitted).
  */
-type ResolvedConfig = Required<Omit<ToonClientConfig, 'connector' | 'mnemonic' | 'mnemonicAccountIndex' | 'evmPrivateKey' | 'network' | 'supportedChains' | 'settlementAddresses' | 'preferredTokens' | 'tokenNetworks' | 'btpUrl' | 'btpAuthToken' | 'btpPeerId' | 'chainRpcUrls' | 'initialDeposit' | 'settlementTimeout' | 'solanaChannel' | 'minaChannel' | 'channelStorePath' | 'knownPeers' | 'destinationAddress' | 'transport' | 'managedAnonProxy' | 'managedAnonSocksPort'>> & {
+type ResolvedConfig = Required<Omit<ToonClientConfig, 'connector' | 'mnemonic' | 'mnemonicAccountIndex' | 'evmPrivateKey' | 'network' | 'supportedChains' | 'settlementAddresses' | 'preferredTokens' | 'tokenNetworks' | 'btpUrl' | 'btpAuthToken' | 'btpPeerId' | 'connectorHttpEndpoint' | 'connectorSupportsUpgrade' | 'chainRpcUrls' | 'initialDeposit' | 'settlementTimeout' | 'solanaChannel' | 'minaChannel' | 'channelStorePath' | 'knownPeers' | 'destinationAddress' | 'transport' | 'managedAnonProxy' | 'managedAnonSocksPort'>> & {
     connector?: unknown;
     /** Always present after applyDefaults() — derived from secretKey if not explicitly provided */
     evmPrivateKey: string | Uint8Array;
@@ -1949,6 +2531,8 @@ type ResolvedConfig = Required<Omit<ToonClientConfig, 'connector' | 'mnemonic' |
     btpUrl?: string;
     btpAuthToken?: string;
     btpPeerId?: string;
+    connectorHttpEndpoint?: string;
+    connectorSupportsUpgrade?: boolean;
     chainRpcUrls?: Record<string, string>;
     initialDeposit?: string;
     settlementTimeout?: number;
@@ -2374,103 +2958,6 @@ declare function filterPetListings(events: NostrEventLike[], options?: PetListin
  */
 declare function buildPetPurchaseRequest(params: PetPurchaseRequestParams): UnsignedNostrEvent;
 
-/**
- * Client-side helper for kind:5094 Arweave blob storage DVM requests.
- *
- * This composes the three steps a caller previously had to wire by hand:
- *   1. Build the kind:5094 event via `buildBlobStorageRequest()` (@toon-protocol/core).
- *   2. Publish it to the DVM destination over ILP via `ToonClient.publishEvent()`
- *      (reusing the existing claim / channel plumbing).
- *   3. Decode the FULFILL `data` field into the Arweave transaction ID.
- *
- * ## FULFILL data contract
- *
- * For a successful single-packet (non-chunked) blob upload, the DVM provider
- * returns the Arweave transaction ID as a **UTF-8 string, base64-encoded** in
- * the ILP FULFILL `data` field (the connector validates that FULFILL data is
- * base64). An Arweave tx ID is a 43-character base64url string (32 raw bytes).
- *
- * So the decode is:
- *   `txId = utf8(base64decode(result.data))`
- *
- * See `packages/sdk/src/arweave/arweave-dvm-handler.ts` for the server side and
- * `packages/client/tests/e2e/docker-arweave-dvm-e2e.test.ts` for the reference
- * end-to-end flow this helper mirrors.
- *
- * Chunked uploads (multi-packet, via `uploadId` / `chunkIndex` / `totalChunks`
- * params) are intentionally out of scope for this single-packet helper — the
- * provider returns `ack:<n>` for intermediate chunks and the tx ID only on the
- * final chunk. Callers needing chunking should drive `publishEvent()` directly
- * (see the chunked case in the reference E2E test). Tracked as a follow-up.
- */
-
-/**
- * Parameters for {@link requestBlobStorage}.
- */
-interface RequestBlobStorageParams {
-    /** The raw blob data to store on Arweave. */
-    blobData: Uint8Array;
-    /**
-     * MIME type of the blob. Defaults to `'application/octet-stream'`
-     * (matching `buildBlobStorageRequest`).
-     */
-    contentType?: string;
-    /**
-     * Bid amount in USDC micro-units, as a string (declared in the event's
-     * `bid` tag). Defaults to the stringified `ilpAmount` when omitted.
-     *
-     * At least one of `bid` / `ilpAmount` should be provided so the declared
-     * bid and the paid ILP amount agree.
-     */
-    bid?: string;
-    /**
-     * ILP destination address of the DVM that performs the upload
-     * (e.g. `'g.toon.peer1'`). Falls back to the client's configured
-     * `destinationAddress` when omitted.
-     */
-    destination?: string;
-    /**
-     * Pre-signed balance proof claim for this packet. When omitted, the
-     * client's channel manager auto-opens a channel and auto-signs a claim
-     * (same lazy-channel behavior as `publishEvent`).
-     */
-    claim?: SignedBalanceProof;
-    /**
-     * Explicit ILP payment amount (bigint micro-units). When omitted,
-     * `publishEvent` computes it from the encoded event size. When `bid`
-     * is omitted, this value is stringified to populate the event's bid tag.
-     */
-    ilpAmount?: bigint;
-}
-/**
- * Typed result of {@link requestBlobStorage}.
- */
-interface RequestBlobStorageResult {
-    /** Whether the upload succeeded and a tx ID was decoded. */
-    success: boolean;
-    /** The Arweave transaction ID (43-char base64url) when `success` is true. */
-    txId?: string;
-    /** The id of the kind:5094 event that was published. */
-    eventId?: string;
-    /** Error message when `success` is false. */
-    error?: string;
-}
-/**
- * Requests permanent Arweave blob storage from a DVM in a single ILP packet.
- *
- * Mirrors the single-packet flow in
- * `packages/client/tests/e2e/docker-arweave-dvm-e2e.test.ts`: builds a signed
- * kind:5094 event, publishes it through the supplied {@link ToonClient}
- * (reusing its claim/channel plumbing), and decodes the FULFILL `data` field
- * into an Arweave transaction ID.
- *
- * @param client - A started `ToonClient` (call `client.start()` first).
- * @param secretKey - The Nostr secret key used to sign the kind:5094 event.
- * @param params - Blob, content type, bid, destination, and payment options.
- * @returns `{ success, txId?, eventId?, error? }`.
- */
-declare function requestBlobStorage(client: ToonClient, secretKey: Uint8Array, params: RequestBlobStorageParams): Promise<RequestBlobStorageResult>;
-
 /**
  * Full multi-chain identity derived from a single BIP-39 mnemonic.
  */
@@ -2820,4 +3307,4 @@ declare function loadKeystore(path: string, password: string): string;
  */
 declare function writeKeystoreFile(path: string, keystore: EncryptedKeystore): void;
 
-export { ANON_ASSETS, ANON_VERSION, type AnonAsset, type BackupPayload, type BalanceProofParams, BtpRuntimeClient, type BtpRuntimeClientConfig, type ChainMetadata, type ChainSigner, ChannelManager, type ClaimMessage, type ClientTransportConfig, ConnectorError, type EVMClaimMessage, type EncryptedKeystore, EvmSigner, HS_HOSTNAME_MAX_LENGTH, HS_HOSTNAME_REGEX, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpRuntimeClient, type HttpRuntimeClientConfig, type InteractionResultContent, KeyManager, type KeyManagerConfig, type ManagedAnonProxy, type MinaClaimMessage, type MinaDepositReader, MinaSigner, type MinaSignerOptions, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type PasskeyInfo, type PetDvmProvider, type PetInteractionEventData, type PetInteractionRequestParams, type PetInteractionResultData, type PetListing, type PetListingFilterOptions, type PetListingParams, type PetPurchaseRequestParams, type ProofStatus, type PublishEventResult, type RequestBlobStorageParams, type RequestBlobStorageResult, type RetryOptions, type SignedBalanceProof, type SolanaChannelClientOptions, type SolanaClaimMessage, SolanaSigner, type StartManagedAnonProxyOptions, type StatValues, ToonClient, type ToonClientConfig, ToonClientError, type ToonIdentity, type ToonSigners, type ToonStartResult, type UnsignedNostrEvent, ValidationError, type VaultData, applyDefaults, applyNetworkPresets, assertRoutableHsHostname, buildBackupEvent, buildBackupFilter, buildPetInteractionRequest, buildPetListingEvent, buildPetPurchaseRequest, buildSettlementInfo, decryptMnemonic, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, filterPetDvmProviders, filterPetListings, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, importKeystore, isPrfSupported, isRoutableHsHostname, loadKeystore, parseBackupPayload, parsePetInteractionEvent, parsePetInteractionResult, parsePetListing, readMinaDepositTotal, requestBlobStorage, selectAnonAsset, startManagedAnonProxy, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };
+export { ANON_ASSETS, ANON_VERSION, type AnonAsset, type BackupPayload, type BalanceProofParams, BtpRuntimeClient, type BtpRuntimeClientConfig, type ChainMetadata, type ChainSigner, ChannelManager, type ClaimMessage, type ClaimResolver, type ClientTransportConfig, ConnectorError, type DiscoveredIlpPeer, type EVMClaimMessage, type EncryptedKeystore, EvmSigner, type H402FetchOptions, HS_HOSTNAME_MAX_LENGTH, HS_HOSTNAME_REGEX, Http402Client, type Http402ClientConfig, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpIlpClient, type HttpIlpClientConfig, type HttpIlpClientFactory, HttpRuntimeClient, type HttpRuntimeClientConfig, ILP_CLAIM_HEADER, ILP_CLAIM_WRAPPED_HEADER, ILP_PEER_ID_HEADER, type IlpTransportChoice, type InteractionResultContent, KeyManager, type KeyManagerConfig, type ManagedAnonProxy, type MinaClaimMessage, type MinaDepositReader, MinaSigner, type MinaSignerOptions, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type ParsedX402Challenge, type PasskeyInfo, type PetDvmProvider, type PetInteractionEventData, type PetInteractionRequestParams, type PetInteractionResultData, type PetListing, type PetListingFilterOptions, type PetListingParams, type PetPurchaseRequestParams, type ProofStatus, type PublishEventResult, type RequestBlobStorageParams, type RequestBlobStorageResult, type RetryOptions, type SelectIlpTransportOptions, type SignedBalanceProof, type SolanaChannelClientOptions, type SolanaClaimMessage, SolanaSigner, type StartManagedAnonProxyOptions, type StatValues, type ToonChannelAccept, ToonClient, type ToonClientConfig, ToonClientError, type ToonIdentity, type ToonSigners, type ToonStartResult, type UnsignedNostrEvent, ValidationError, type VaultData, applyDefaults, applyNetworkPresets, assertRoutableHsHostname, buildBackupEvent, buildBackupFilter, buildPetInteractionRequest, buildPetListingEvent, buildPetPurchaseRequest, buildSettlementInfo, decryptMnemonic, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, filterPetDvmProviders, filterPetListings, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, httpEndpointToBtpUrl, importKeystore, isPrfSupported, isRoutableHsHostname, loadKeystore, parseBackupPayload, parseHttpResponse, parsePetInteractionEvent, parsePetInteractionResult, parsePetListing, parseX402Body, parseX402Challenge, readDiscoveredIlpPeer, readMinaDepositTotal, requestBlobStorage, selectAnonAsset, selectIlpTransport, serializeHttpRequest, startManagedAnonProxy, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };