@fiber-dev-kit/test-client 0.1.0-rc.0

package/CONTRIBUTION.md

@@ -0,0 +1,38 @@
+# Contributing to @fiber-dev-kit/test-client
+
+Thanks for helping improve the Fiber Dev Kit test client.
+
+## Scope
+
+This package provides programmable test helpers for Fiber payment and channel flows. It should make local testnets and CI checks easier without hiding important Fiber behavior.
+
+Typical changes include:
+
+- Multi-node test orchestration.
+- Payment and channel assertions.
+- Polling utilities.
+- Route confidence checks.
+- Terminal output improvements.
+
+## Local Development
+
+From the workspace root:
+
+```bash
+npm install
+npm run build --workspace @fiber-dev-kit/test-client
+npm run typecheck --workspace @fiber-dev-kit/test-client
+npm test --workspace @fiber-dev-kit/test-client
+```
+
+## Guidelines
+
+- Keep assertions deterministic and useful for failing Fiber payment tests.
+- Do not swallow failures silently. Return structured diagnostics where possible.
+- Keep terminal formatting readable in both local terminals and CI logs.
+- Add tests for new polling behavior, assertions, and failure paths.
+- Use `@fiber-dev-kit/core` for shared RPC, diagnostics, amount, and route logic instead of duplicating it here.
+
+## Release Notes
+
+When changing test behavior, document any assertion semantics that changed. Include examples for new helpers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fiber Dev Kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @fiber-dev-kit/test-client
+
+Programmatic test helpers for Fiber payment, channel, and routing flows.
+
+The test client builds on `@fiber-dev-kit/core` and is intended for local testnets, CI smoke tests, hackathon demos, and repeatable Fiber payment experiments.
+
+## Install
+
+```bash
+npm install @fiber-dev-kit/test-client
+```
+
+## Usage
+
+```ts
+import { FiberNetwork } from "@fiber-dev-kit/test-client";
+
+const network = new FiberNetwork({
+  nodes: {
+    a: "http://127.0.0.1:8227",
+    b: "http://127.0.0.1:8237",
+  },
+});
+
+await network.expectNodeHealthy("a");
+
+const report = await network.canPay({
+  from: "a",
+  to: "b",
+  amount: "1",
+});
+
+console.log(report);
+```
+
+## What it provides
+
+- Multi-node test wrapper around Fiber RPC clients.
+- Payment and channel assertions.
+- Polling utilities for async Fiber state transitions.
+- Pretty terminal output for local test runs.
+- Route confidence checks backed by `@fiber-dev-kit/core`.
+
+## Requirements
+
+- Node.js 18 or newer.
+- Published `@fiber-dev-kit/core` matching this package version.
+- One or more reachable Fiber node JSON-RPC endpoints.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { FiberTestClient } from "./test-client";
+export type { TestClientConfig, PayParams, RouteConfidenceReport } from "./test-client";
+export { FiberNetwork } from "./network";
+export type { FiberNetworkConfig, NetworkNodeConfig, NetworkTopology, SimulationResult } from "./network";
+export { pollUntilResolved, sleep } from "./poller";
+export type { PollOptions } from "./poller";
+export { formatDiagnosis, formatRouteConfidenceReport, formatSimulationResult } from "./terminal";
+export type { TerminalFormatOptions } from "./terminal";
+export { diagnose, diagnosePayment, FiberError } from "@fiber-dev-kit/core";
+export type { Diagnosis, DiagnosisCode, PaymentResult, HexString } from "@fiber-dev-kit/core";

package/dist/index.js

@@ -0,0 +1,421 @@
+// src/test-client.ts
+import { FiberClient, FiberEventClient, diagnose, diagnosePayment, FiberError, shannonHexToCkb } from "@fiber-dev-kit/core";
+
+// src/poller.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function pollUntilResolved(fetchValue, isResolved, options = {}) {
+  const intervalMs = options.intervalMs ?? 500;
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const deadline = Date.now() + timeoutMs;
+  let value = await fetchValue();
+  while (!isResolved(value)) {
+    if (Date.now() >= deadline) {
+      throw new Error(`pollUntilResolved: condition not met within ${timeoutMs}ms`);
+    }
+    await sleep(intervalMs);
+    value = await fetchValue();
+  }
+  return value;
+}
+
+// src/test-client.ts
+var TERMINAL_PAYMENT_STATUSES = /* @__PURE__ */ new Set(["Success", "Failed"]);
+var FiberTestClient = class {
+  rpc;
+  events;
+  pollIntervalMs;
+  timeoutMs;
+  constructor(config) {
+    if (config.network === "mainnet") {
+      throw new Error('FiberTestClient refuses network: "mainnet" \u2014 it exists for devnet/testnet testing only.');
+    }
+    this.pollIntervalMs = config.pollIntervalMs ?? 500;
+    this.timeoutMs = config.timeoutMs ?? 1e4;
+    this.rpc = new FiberClient({ nodeUrl: config.nodeUrl, network: config.network ?? "devnet" });
+    this.events = new FiberEventClient({ client: this.rpc, pollIntervalMs: this.pollIntervalMs });
+  }
+  /** Pays an invoice, or keysends directly to a pubkey with an explicit amount. */
+  pay(params) {
+    if ("invoice" in params) {
+      return this.rpc.payInvoice(params.invoice);
+    }
+    return this.rpc.sendPayment({ targetPubkey: params.to, amount: params.amount, keysend: true });
+  }
+  /** Dry-runs a payment to check routability/fees without sending. Returns `null` if it wouldn't succeed. */
+  async canPay(params) {
+    try {
+      if ("invoice" in params) {
+        return await this.rpc.sendPayment({ invoice: params.invoice, dryRun: true });
+      }
+      return await this.rpc.sendPayment({ targetPubkey: params.to, amount: params.amount, keysend: true, dryRun: true });
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Produces a small route-confidence report from local health signals plus FNN's dry-run
+   * payment result. It is a practical preflight check, not a full network graph score.
+   */
+  async routeConfidence(params) {
+    const reasons = [];
+    const suggestions = [];
+    let score = 100;
+    const [peers, channels] = await Promise.all([
+      this.rpc.listPeers().catch(() => []),
+      this.rpc.listChannels({ includeClosed: true }).catch(() => [])
+    ]);
+    const readyChannels = channels.filter((channel) => channel.state.state_name === "ChannelReady");
+    if (peers.length === 0) {
+      score -= 30;
+      reasons.push("Node has no connected peers.");
+      suggestions.push("Connect to at least one reachable peer before testing routed payments.");
+    }
+    if (readyChannels.length === 0) {
+      score -= 40;
+      reasons.push("Node has no ChannelReady channels.");
+      suggestions.push("Open a channel and wait for ChannelReady before sending payments.");
+    }
+    if ("to" in params) {
+      score = applyKeysendLiquiditySignal(score, params, readyChannels, reasons, suggestions);
+    }
+    let dryRunPayment = null;
+    let diagnosis = null;
+    try {
+      dryRunPayment = "invoice" in params ? await this.rpc.sendPayment({ invoice: params.invoice, dryRun: true }) : await this.rpc.sendPayment({ targetPubkey: params.to, amount: params.amount, keysend: true, dryRun: true });
+      reasons.push("FNN dry-run accepted the payment.");
+      score = Math.max(score, 90);
+    } catch (err) {
+      score = Math.min(score - 30, 40);
+      if (FiberError.is(err)) {
+        diagnosis = diagnose(err);
+        reasons.push(diagnosis.summary);
+        suggestions.push(diagnosis.suggestion);
+      } else {
+        reasons.push(`Dry-run failed: ${err.message}`);
+        suggestions.push("Inspect the thrown error and retry after correcting the route or invoice.");
+      }
+    }
+    const normalizedScore = Math.max(0, Math.min(100, score));
+    return {
+      canPay: dryRunPayment !== null,
+      score: normalizedScore,
+      level: confidenceLevel(normalizedScore),
+      reasons,
+      suggestions: [...new Set(suggestions)],
+      dryRunPayment,
+      diagnosis
+    };
+  }
+  waitForPayment(paymentHash) {
+    return pollUntilResolved(
+      () => this.rpc.getPayment(paymentHash),
+      (payment) => TERMINAL_PAYMENT_STATUSES.has(payment.status),
+      { intervalMs: this.pollIntervalMs, timeoutMs: this.timeoutMs }
+    );
+  }
+  async assertPaid(paymentHash) {
+    const payment = await this.waitForPayment(paymentHash);
+    if (payment.status !== "Success") {
+      const diagnosis = diagnosePayment(payment);
+      throw new Error(
+        `Expected payment ${paymentHash} to succeed, got status "${payment.status}"` + (diagnosis ? ` \u2014 ${diagnosis.summary} (${diagnosis.suggestion})` : "")
+      );
+    }
+    return payment;
+  }
+  async assertFailed(paymentHash) {
+    const payment = await this.waitForPayment(paymentHash);
+    if (payment.status !== "Failed") {
+      throw new Error(`Expected payment ${paymentHash} to fail, got status "${payment.status}"`);
+    }
+    return payment;
+  }
+  /** Asserts a payment failed for a specific, structured reason (see `diagnose()` in core). */
+  async assertError(paymentHash, expectedCode) {
+    const payment = await this.assertFailed(paymentHash);
+    const diagnosis = diagnosePayment(payment);
+    if (!diagnosis) {
+      throw new Error(
+        `Payment ${paymentHash} failed, but FNN reported no failure reason (failed_error was empty) \u2014 cannot verify it matches "${expectedCode}".`
+      );
+    }
+    if (diagnosis.code !== expectedCode) {
+      throw new Error(
+        `Expected payment ${paymentHash} to fail with "${expectedCode}", got "${diagnosis.code}": ${diagnosis.summary}`
+      );
+    }
+    return diagnosis;
+  }
+  async getChannelBalance(channelId) {
+    const channels = await this.rpc.listChannels({ includeClosed: true });
+    const channel = channels.find((c) => c.channel_id === channelId);
+    if (!channel) {
+      throw new Error(`getChannelBalance(): no channel with id ${channelId} found on this node.`);
+    }
+    return { local: shannonHexToCkb(channel.local_balance), remote: shannonHexToCkb(channel.remote_balance) };
+  }
+  /** Pays `to` repeatedly until this channel's outbound capacity is exhausted (minus 1 CKB for fees). */
+  async drainChannel(channelId, to) {
+    const { local } = await this.getChannelBalance(channelId);
+    const amount = Math.floor(local) - 1;
+    if (amount <= 0) return;
+    const result = await this.pay({ to, amount });
+    await this.waitForPayment(result.payment_hash);
+  }
+};
+function applyKeysendLiquiditySignal(score, params, readyChannels, reasons, suggestions) {
+  const candidateChannels = readyChannels.filter((channel) => !channel.peer_id || channel.peer_id === params.to);
+  if (candidateChannels.length === 0) return score;
+  const bestLocalBalance = Math.max(...candidateChannels.map((channel) => shannonHexToCkb(channel.local_balance)));
+  if (bestLocalBalance < params.amount) {
+    reasons.push(`Best matching channel has ${bestLocalBalance} CKB outbound balance, below the ${params.amount} CKB payment.`);
+    suggestions.push("Reduce the payment amount, rebalance the channel, or open more outbound liquidity.");
+    return score - 25;
+  }
+  reasons.push(`A ready channel has enough local balance for ${params.amount} CKB before fees.`);
+  return score;
+}
+function confidenceLevel(score) {
+  if (score >= 80) return "high";
+  if (score >= 50) return "medium";
+  return "low";
+}
+
+// src/network.ts
+import { diagnose as diagnose2, diagnosePayment as diagnosePayment2, FiberError as FiberError2 } from "@fiber-dev-kit/core";
+var FiberNetwork = class {
+  clients = /* @__PURE__ */ new Map();
+  pubkeys = /* @__PURE__ */ new Map();
+  pollIntervalMs;
+  timeoutMs;
+  simulate;
+  constructor(config) {
+    this.pollIntervalMs = config.pollIntervalMs ?? 1e3;
+    this.timeoutMs = config.timeoutMs ?? 6e4;
+    for (const [alias, nodeConfig] of Object.entries(config.nodes)) {
+      const resolved = typeof nodeConfig === "string" ? { nodeUrl: nodeConfig } : nodeConfig;
+      this.clients.set(
+        alias,
+        new FiberTestClient({ ...resolved, pollIntervalMs: this.pollIntervalMs, timeoutMs: this.timeoutMs })
+      );
+    }
+    this.simulate = new NetworkSimulations(this);
+  }
+  node(alias) {
+    const client = this.clients.get(alias);
+    if (!client) {
+      throw new Error(`FiberNetwork: no node registered under alias "${alias}". Known aliases: ${[...this.clients.keys()].join(", ") || "(none)"}`);
+    }
+    return client;
+  }
+  /** Waits until every configured node's RPC is reachable. Does not start any process. */
+  async start() {
+    await Promise.all(
+      [...this.clients.values()].map(
+        (client) => pollUntilResolved(
+          () => client.rpc.info().then(() => true, () => false),
+          (ok) => ok,
+          { intervalMs: this.pollIntervalMs, timeoutMs: this.timeoutMs }
+        )
+      )
+    );
+  }
+  async pubkeyOf(alias) {
+    let pubkey = this.pubkeys.get(alias);
+    if (!pubkey) {
+      const info = await this.node(alias).rpc.info();
+      pubkey = info.pubkey;
+      this.pubkeys.set(alias, pubkey);
+    }
+    return pubkey;
+  }
+  /** Connects `fromAlias` to `toAlias` by pubkey/address, unless already peered. */
+  async connect(fromAlias, toAlias) {
+    const from = this.node(fromAlias);
+    const toInfo = await this.node(toAlias).rpc.info();
+    const alreadyConnected = (await from.rpc.listPeers()).some((peer) => peer.pubkey === toInfo.pubkey);
+    if (alreadyConnected) return;
+    const address = toInfo.addresses[0];
+    if (!address) {
+      throw new Error(
+        `connect(): node "${toAlias}" has no advertised address in info().addresses. It may not be listening publicly \u2014 connect it manually with a known multiaddr instead.`
+      );
+    }
+    await from.rpc.connectPeer({ address });
+  }
+  /** Connects (if needed), opens a channel, and waits until it's `ChannelReady` on the funder's side. */
+  async openChannel(fromAlias, toAlias, capacityCkb) {
+    await this.connect(fromAlias, toAlias);
+    const from = this.node(fromAlias);
+    const toPubkey = await this.pubkeyOf(toAlias);
+    await from.rpc.openChannel({ pubkey: toPubkey, fundingAmount: capacityCkb });
+    const ready = await pollUntilResolved(
+      () => from.rpc.listChannels({ pubkey: toPubkey }),
+      (channels) => channels.some((c) => c.state.state_name === "ChannelReady"),
+      { intervalMs: this.pollIntervalMs, timeoutMs: this.timeoutMs }
+    );
+    return ready.find((c) => c.state.state_name === "ChannelReady").channel_id;
+  }
+  /** Creates an invoice on `toAlias` and pays it from `fromAlias`. */
+  async pay(fromAlias, toAlias, amountCkb, opts = {}) {
+    const to = this.node(toAlias);
+    const from = this.node(fromAlias);
+    const { invoice_address } = await to.rpc.createInvoice({
+      amount: amountCkb,
+      description: opts.description ?? `${fromAlias} -> ${toAlias}`
+    });
+    return from.pay({ invoice: invoice_address });
+  }
+};
+var NetworkSimulations = class {
+  constructor(network) {
+    this.network = network;
+  }
+  network;
+  /** Drains `channelId`'s outbound capacity from `fromAlias`, then overpays past it. */
+  async insufficientLiquidity(fromAlias, toAlias, channelId) {
+    const from = this.network.node(fromAlias);
+    const toPubkey = await this.network.pubkeyOf(toAlias);
+    const { local } = await from.getChannelBalance(channelId);
+    if (local > 1) {
+      await from.drainChannel(channelId, toPubkey);
+    }
+    return this.attempt(() => this.network.pay(fromAlias, toAlias, local + 1));
+  }
+  /** Pays a node with no route to it (never connected, no channel path). */
+  async unreachablePeer(fromAlias, targetAlias, amountCkb) {
+    const from = this.network.node(fromAlias);
+    const targetPubkey = await this.network.pubkeyOf(targetAlias);
+    return this.attempt(() => from.pay({ to: targetPubkey, amount: amountCkb }));
+  }
+  /** Creates a 1-second-expiry invoice, waits it out, then tries to pay it. */
+  async expiredInvoice(fromAlias, toAlias, amountCkb) {
+    const to = this.network.node(toAlias);
+    const from = this.network.node(fromAlias);
+    const { invoice_address } = await to.rpc.createInvoice({
+      amount: amountCkb,
+      expiry: 1,
+      description: "simulate.expiredInvoice"
+    });
+    await sleep(1500);
+    return this.attempt(() => from.pay({ invoice: invoice_address }));
+  }
+  async attempt(send) {
+    try {
+      const payment = await send();
+      return { payment, diagnosis: diagnosePayment2(payment) };
+    } catch (err) {
+      if (FiberError2.is(err)) {
+        return { payment: null, diagnosis: diagnose2(err) };
+      }
+      throw err;
+    }
+  }
+};
+
+// src/terminal.ts
+import { Chalk } from "chalk";
+var DEFAULT_WIDTH = 72;
+function formatRouteConfidenceReport(report, options = {}) {
+  const out = new TerminalFormatter(options);
+  out.section("Route Confidence");
+  out.rows([
+    ["Can pay", report.canPay ? "yes" : "no"],
+    ["Score", `${report.score}/100`],
+    ["Level", report.level],
+    ["Dry-run", report.dryRunPayment ? `accepted (${report.dryRunPayment.status})` : "rejected"]
+  ]);
+  out.list("Reasons", report.reasons);
+  out.list("Suggestions", report.suggestions);
+  if (report.diagnosis) out.diagnosis(report.diagnosis);
+  return out.toString();
+}
+function formatSimulationResult(title, result, options = {}) {
+  const out = new TerminalFormatter(options);
+  out.section(title);
+  out.status(result.payment ? "INFO" : "FAIL", result.payment ? "Payment attempt returned a payment record." : "Payment attempt failed before submission.");
+  if (result.payment) {
+    out.rows([
+      ["Payment", result.payment.payment_hash],
+      ["Status", result.payment.status],
+      ["Fee", result.payment.fee]
+    ]);
+  }
+  if (result.diagnosis) out.diagnosis(result.diagnosis);
+  return out.toString();
+}
+function formatDiagnosis(diagnosis, options = {}) {
+  const out = new TerminalFormatter(options);
+  out.diagnosis(diagnosis);
+  return out.toString();
+}
+var TerminalFormatter = class {
+  chalk;
+  width;
+  lines = [];
+  constructor(options) {
+    const color = options.color ?? Boolean(process.stdout.isTTY && !process.env.NO_COLOR);
+    this.chalk = new Chalk({ level: color ? 1 : 0 });
+    this.width = options.width ?? DEFAULT_WIDTH;
+  }
+  section(title) {
+    this.lines.push("");
+    this.lines.push(this.chalk.bold(title));
+    this.lines.push(this.chalk.dim("-".repeat(Math.min(title.length, this.width))));
+  }
+  status(kind, message) {
+    this.lines.push(`  ${this.badge(kind)} ${message}`);
+  }
+  rows(rows, labelWidth = 14) {
+    for (const [label, value] of rows) {
+      this.lines.push(`  ${this.chalk.dim(label.padEnd(labelWidth))} ${value}`);
+    }
+  }
+  list(title, items) {
+    if (items.length === 0) return;
+    this.lines.push("");
+    this.lines.push(`  ${this.chalk.bold(title)}`);
+    for (const item of items) {
+      this.lines.push(`  - ${item}`);
+    }
+  }
+  diagnosis(diagnosis) {
+    this.lines.push("");
+    this.lines.push(`  ${this.chalk.bold("Diagnosis")}`);
+    this.rows(
+      [
+        ["Code", this.chalk.bold(diagnosis.code)],
+        ["Summary", diagnosis.summary],
+        ["Suggestion", diagnosis.suggestion]
+      ],
+      12
+    );
+  }
+  toString() {
+    return this.lines.join("\n");
+  }
+  badge(kind) {
+    const text = `[${kind}]`;
+    if (kind === "PASS") return this.chalk.green(text);
+    if (kind === "FAIL") return this.chalk.red(text);
+    if (kind === "SKIP") return this.chalk.yellow(text);
+    return this.chalk.cyan(text);
+  }
+};
+
+// src/index.ts
+import { diagnose as diagnose3, diagnosePayment as diagnosePayment3, FiberError as FiberError3 } from "@fiber-dev-kit/core";
+export {
+  FiberError3 as FiberError,
+  FiberNetwork,
+  FiberTestClient,
+  diagnose3 as diagnose,
+  diagnosePayment3 as diagnosePayment,
+  formatDiagnosis,
+  formatRouteConfidenceReport,
+  formatSimulationResult,
+  pollUntilResolved,
+  sleep
+};

package/dist/network.d.ts

@@ -0,0 +1,55 @@
+import type { Diagnosis, HexString, NetworkMode, PaymentResult } from "@fiber-dev-kit/core";
+import { FiberTestClient } from "./test-client";
+export interface NetworkNodeConfig {
+    nodeUrl: string;
+    network?: Exclude<NetworkMode, "mainnet">;
+}
+/** Alias (e.g. `"a"`, `"b"`) → an already-running node's RPC URL or config. */
+export type NetworkTopology = Record<string, string | NetworkNodeConfig>;
+export interface FiberNetworkConfig {
+    nodes: NetworkTopology;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+}
+export interface SimulationResult {
+    payment: PaymentResult | null;
+    diagnosis: Diagnosis | null;
+}
+/**
+ * Multi-node test orchestration. Wraps one `FiberTestClient` per alias and never spawns or
+ * manages `fnn` processes — point it at nodes that are already running (via the fiber-devkit
+ * CLI, manually, or however your team's launcher of the day works).
+ */
+export declare class FiberNetwork {
+    private readonly clients;
+    private readonly pubkeys;
+    private readonly pollIntervalMs;
+    private readonly timeoutMs;
+    readonly simulate: NetworkSimulations;
+    constructor(config: FiberNetworkConfig);
+    node(alias: string): FiberTestClient;
+    /** Waits until every configured node's RPC is reachable. Does not start any process. */
+    start(): Promise<void>;
+    pubkeyOf(alias: string): Promise<HexString>;
+    /** Connects `fromAlias` to `toAlias` by pubkey/address, unless already peered. */
+    connect(fromAlias: string, toAlias: string): Promise<void>;
+    /** Connects (if needed), opens a channel, and waits until it's `ChannelReady` on the funder's side. */
+    openChannel(fromAlias: string, toAlias: string, capacityCkb: number): Promise<HexString>;
+    /** Creates an invoice on `toAlias` and pays it from `fromAlias`. */
+    pay(fromAlias: string, toAlias: string, amountCkb: number, opts?: {
+        description?: string;
+    }): Promise<PaymentResult>;
+}
+/** Named failure-scenario helpers, built from primitives already in `core`. */
+declare class NetworkSimulations {
+    private readonly network;
+    constructor(network: FiberNetwork);
+    /** Drains `channelId`'s outbound capacity from `fromAlias`, then overpays past it. */
+    insufficientLiquidity(fromAlias: string, toAlias: string, channelId: HexString): Promise<SimulationResult>;
+    /** Pays a node with no route to it (never connected, no channel path). */
+    unreachablePeer(fromAlias: string, targetAlias: string, amountCkb: number): Promise<SimulationResult>;
+    /** Creates a 1-second-expiry invoice, waits it out, then tries to pay it. */
+    expiredInvoice(fromAlias: string, toAlias: string, amountCkb: number): Promise<SimulationResult>;
+    private attempt;
+}
+export {};

package/dist/poller.d.ts

@@ -0,0 +1,7 @@
+export interface PollOptions {
+    intervalMs?: number;
+    timeoutMs?: number;
+}
+export declare function sleep(ms: number): Promise<void>;
+/** Polls `fetch()` until `isResolved()` accepts a value, or throws once `timeoutMs` elapses. */
+export declare function pollUntilResolved<T>(fetchValue: () => Promise<T>, isResolved: (value: T) => boolean, options?: PollOptions): Promise<T>;

package/dist/terminal.d.ts

@@ -0,0 +1,10 @@
+import type { Diagnosis } from "@fiber-dev-kit/core";
+import type { RouteConfidenceReport } from "./test-client";
+import type { SimulationResult } from "./network";
+export interface TerminalFormatOptions {
+    color?: boolean;
+    width?: number;
+}
+export declare function formatRouteConfidenceReport(report: RouteConfidenceReport, options?: TerminalFormatOptions): string;
+export declare function formatSimulationResult(title: string, result: SimulationResult, options?: TerminalFormatOptions): string;
+export declare function formatDiagnosis(diagnosis: Diagnosis, options?: TerminalFormatOptions): string;

package/dist/test-client.d.ts

@@ -0,0 +1,64 @@
+import { FiberClient, FiberEventClient } from "@fiber-dev-kit/core";
+import type { Diagnosis, DiagnosisCode, HexString, NetworkMode, PaymentResult } from "@fiber-dev-kit/core";
+export interface TestClientConfig {
+    nodeUrl: string;
+    /**
+     * Mainnet is refused outright at runtime (throws in the constructor) — this client sends
+     * real test/keysend payments and drains channels. Typed as the full `NetworkMode` (rather
+     * than excluding `"mainnet"`) so that check isn't silently optimized away as dead code by
+     * callers who do have `"mainnet"` in a variable's inferred type.
+     */
+    network?: NetworkMode;
+    /** Default poll interval for `waitForPayment()`. Default: 500ms. */
+    pollIntervalMs?: number;
+    /** Default timeout for `waitForPayment()`. Default: 10000ms. */
+    timeoutMs?: number;
+}
+export type PayParams = {
+    invoice: string;
+    amount?: never;
+} | {
+    to: HexString;
+    amount: number;
+};
+export interface RouteConfidenceReport {
+    canPay: boolean;
+    score: number;
+    level: "high" | "medium" | "low";
+    reasons: string[];
+    suggestions: string[];
+    dryRunPayment: PaymentResult | null;
+    diagnosis: Diagnosis | null;
+}
+/**
+ * Single-node test API. Built entirely on `@fiber-dev-kit/core` — no RPC calls of its own.
+ * Assumes the node at `nodeUrl` is already running; this package never spawns or manages
+ * `fnn` processes (that's the CLI's job).
+ */
+export declare class FiberTestClient {
+    readonly rpc: FiberClient;
+    readonly events: FiberEventClient;
+    private readonly pollIntervalMs;
+    private readonly timeoutMs;
+    constructor(config: TestClientConfig);
+    /** Pays an invoice, or keysends directly to a pubkey with an explicit amount. */
+    pay(params: PayParams): Promise<PaymentResult>;
+    /** Dry-runs a payment to check routability/fees without sending. Returns `null` if it wouldn't succeed. */
+    canPay(params: PayParams): Promise<PaymentResult | null>;
+    /**
+     * Produces a small route-confidence report from local health signals plus FNN's dry-run
+     * payment result. It is a practical preflight check, not a full network graph score.
+     */
+    routeConfidence(params: PayParams): Promise<RouteConfidenceReport>;
+    waitForPayment(paymentHash: HexString): Promise<PaymentResult>;
+    assertPaid(paymentHash: HexString): Promise<PaymentResult>;
+    assertFailed(paymentHash: HexString): Promise<PaymentResult>;
+    /** Asserts a payment failed for a specific, structured reason (see `diagnose()` in core). */
+    assertError(paymentHash: HexString, expectedCode: DiagnosisCode): Promise<Diagnosis>;
+    getChannelBalance(channelId: HexString): Promise<{
+        local: number;
+        remote: number;
+    }>;
+    /** Pays `to` repeatedly until this channel's outbound capacity is exhausted (minus 1 CKB for fees). */
+    drainChannel(channelId: HexString, to: HexString): Promise<void>;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@fiber-dev-kit/test-client",
+  "version": "0.1.0-rc.0",
+  "description": "Programmatic TypeScript test API for Fiber payment and channel flows",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/scisamir/fiber-dev-kit.git",
+    "directory": "test-client"
+  },
+  "bugs": {
+    "url": "https://github.com/scisamir/fiber-dev-kit/issues"
+  },
+  "homepage": "https://github.com/scisamir/fiber-dev-kit#readme",
+  "keywords": [
+    "ckb",
+    "fiber-network",
+    "nervos",
+    "payments",
+    "testing"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "rc"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CONTRIBUTION.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean && tsc --emitDeclarationOnly --declaration",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@fiber-dev-kit/core": "0.1.0-rc.0",
+    "chalk": "^5.6.2"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "tsup": "^8.0.1",
+    "typescript": "^5.4.0",
+    "vitest": "^1.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}