@toon-protocol/client 0.9.2 → 0.10.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,72 @@ 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/ToonClient.ts
 var ToonClient = class {
   config;
@@ -3355,6 +3667,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
@@ -4735,74 +5069,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 +5856,7 @@ var KeyManager = class {
       this.vault,
       this.identity.nostr.secretKey
     );
-    const signedEvent = finalizeEvent(
+    const signedEvent = finalizeEvent2(
       eventTemplate,
       this.identity.nostr.secretKey
     );
@@ -5850,7 +6118,11 @@ export {
   HS_HOSTNAME_MAX_LENGTH,
   HS_HOSTNAME_REGEX,
   HttpConnectorAdmin,
+  HttpIlpClient,
   HttpRuntimeClient,
+  ILP_CLAIM_HEADER,
+  ILP_CLAIM_WRAPPED_HEADER,
+  ILP_PEER_ID_HEADER,
   KeyManager,
   MinaSigner,
   NetworkError,
@@ -5879,6 +6151,7 @@ export {
   generateMnemonic,
   generateRandomIdentity,
   getNetworkStatus,
+  httpEndpointToBtpUrl,
   importKeystore,
   isPrfSupported,
   isRoutableHsHostname,
@@ -5887,9 +6160,11 @@ export {
   parsePetInteractionEvent,
   parsePetInteractionResult,
   parsePetListing,
+  readDiscoveredIlpPeer,
   readMinaDepositTotal,
   requestBlobStorage,
   selectAnonAsset,
+  selectIlpTransport,
   startManagedAnonProxy,
   validateConfig,
   validateMnemonic,