@fiber-dev-kit/core 0.1.0-rc.0

package/CONTRIBUTION.md

@@ -0,0 +1,39 @@
+# Contributing to @fiber-dev-kit/core
+
+Thanks for helping improve the Fiber Dev Kit core package.
+
+## Scope
+
+This package contains the shared TypeScript foundation for the devkit:
+
+- Fiber JSON-RPC client helpers.
+- Fiber node, peer, channel, invoice, and payment types.
+- Amount conversion utilities.
+- Payment diagnostics.
+- Node alert rules.
+- Route confidence helpers.
+
+Keep changes focused on shared behavior that belongs below the inspector and test client packages.
+
+## Local Development
+
+From the workspace root:
+
+```bash
+npm install
+npm run build --workspace @fiber-dev-kit/core
+npm run typecheck --workspace @fiber-dev-kit/core
+npm test --workspace @fiber-dev-kit/core
+```
+
+## Guidelines
+
+- Preserve the public API unless the version is being intentionally bumped for a breaking change.
+- Add or update tests for diagnostics, amount conversion, RPC wrapping, alert rules, and route confidence behavior.
+- Keep Fiber RPC types close to the node API shape. Add ergonomic wrapper types separately when needed.
+- Avoid introducing browser-only dependencies. This package targets Node.js 18 and newer.
+- Prefer small, explicit helpers over broad abstractions.
+
+## Release Notes
+
+When changing behavior, document the user-facing impact in the pull request or release notes. Include migration notes for renamed exports, changed error codes, or changed amount handling.

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,68 @@
+# @fiber-dev-kit/core
+
+Network-aware TypeScript helpers for working with Fiber Network Node JSON-RPC APIs.
+
+This package is not a replacement for official Fiber SDKs. It is support infrastructure for local node diagnostics, test automation, and hackathon-grade developer tooling.
+
+## Install
+
+```bash
+npm install @fiber-dev-kit/core
+```
+
+## Usage
+
+```ts
+import {
+  FiberClient,
+  diagnosePaymentFailure,
+  evaluateNodeAlerts,
+  routeConfidence,
+} from "@fiber-dev-kit/core";
+
+const node = new FiberClient({
+  name: "a",
+  url: "http://127.0.0.1:8227",
+});
+
+const info = await node.getInfo();
+const peers = await node.listPeers();
+const channels = await node.listChannels();
+
+const alerts = evaluateNodeAlerts({
+  name: "a",
+  info,
+  peers,
+  channels,
+});
+
+const confidence = await routeConfidence({
+  from: node,
+  to: "0372...",
+  amount: "1",
+});
+
+try {
+  await node.sendPayment({ invoice: "..." });
+} catch (error) {
+  console.error(diagnosePaymentFailure(error));
+}
+```
+
+## What it provides
+
+- A small Fiber JSON-RPC client.
+- Amount conversion helpers for CKB/shannons.
+- Payment failure diagnosis helpers.
+- Node and channel alert rules.
+- Route confidence and `canPay` style reports for local testing.
+- Typed Fiber node, channel, invoice, and payment shapes used by the devkit packages.
+
+## Requirements
+
+- Node.js 18 or newer.
+- A reachable Fiber node JSON-RPC endpoint.
+
+## License
+
+MIT

package/dist/alerts.d.ts

@@ -0,0 +1,37 @@
+import { type Diagnosis } from "./diagnostics";
+import type { Channel } from "./types/channel";
+import type { HexString } from "./types/common";
+import type { NodeInfo, PeerInfo } from "./types/node";
+import type { PaymentResult } from "./types/payment";
+export type AlertSeverity = "info" | "warning" | "critical";
+export type AlertCode = "NODE_UNREACHABLE" | "ZERO_PEERS" | "NO_READY_CHANNELS" | "LOW_LOCAL_BALANCE" | "PAYMENT_FAILED";
+export interface Alert {
+    code: AlertCode;
+    severity: AlertSeverity;
+    summary: string;
+    suggestion: string;
+    nodeId?: string;
+    channelId?: HexString;
+    paymentHash?: HexString;
+    diagnosis?: Diagnosis | null;
+}
+export interface AlertRules {
+    /** Emit ZERO_PEERS when true. Default: true. */
+    requirePeers?: boolean;
+    /** Emit NO_READY_CHANNELS when true. Default: true. */
+    requireReadyChannels?: boolean;
+    /** Emit LOW_LOCAL_BALANCE below this ready-channel outbound balance. Default: 1 CKB. */
+    minLocalBalanceCkb?: number;
+    /** Emit PAYMENT_FAILED for recent failed payments when true. Default: true. */
+    includeFailedPayments?: boolean;
+}
+export interface AlertSnapshot {
+    nodeId?: string;
+    node?: NodeInfo;
+    nodeError?: unknown;
+    peers?: PeerInfo[];
+    channels?: Channel[];
+    payments?: PaymentResult[];
+}
+/** Evaluates a node snapshot into actionable operational alerts for CLIs, UIs, or tests. */
+export declare function evaluateAlerts(snapshot: AlertSnapshot, rules?: AlertRules): Alert[];

package/dist/client.d.ts

@@ -0,0 +1,86 @@
+import type { HexString } from "./types/common";
+import type { ConnectPeerParams, DisconnectPeerParams, NodeInfo, PeerInfo } from "./types/node";
+import type { AbandonChannelParams, AcceptChannelParams, AcceptChannelResult, Channel, ListChannelsParams, OpenChannelParams, OpenChannelResult, ShutdownChannelParams, UpdateChannelParams } from "./types/channel";
+import type { CancelInvoiceParams, CkbInvoice, GetInvoiceResult, InvoiceCurrency, NewInvoiceParams, NewInvoiceResult, SettleInvoiceParams } from "./types/invoice";
+import type { GetPaymentParams, ListPaymentsParams, PaymentResult, SendPaymentParams } from "./types/payment";
+import type { NetworkMode } from "./types/network";
+export interface FiberClientConfig {
+    /** RPC endpoint of the node, e.g. `http://127.0.0.1:8227`. */
+    nodeUrl: string;
+    /** Bearer token, if the node's RPC has auth enabled. */
+    authToken?: string;
+    /** Request timeout in ms. Default: 30000. */
+    timeoutMs?: number;
+    /** Currency used by `createInvoice`/`sendPayment` when not given explicitly. Default: `Fibt` (testnet). */
+    defaultCurrency?: InvoiceCurrency;
+    /**
+     * Which network `nodeUrl` points at. Unset means "unknown" and no guard is applied — set
+     * this to `"mainnet"` to get the write-guard below for free; it costs nothing on
+     * devnet/testnet.
+     */
+    network?: NetworkMode;
+    /**
+     * Explicit opt-in to run fund-moving calls (`openChannel`, `acceptChannel`,
+     * `abandonChannel`, `shutdownChannel`, `sendPayment`/`payInvoice`) when `network` is
+     * `"mainnet"`. Default: false. This exists to catch the mistake that actually loses
+     * money — a test/demo script pointed at the wrong `nodeUrl` — not to stop legitimate
+     * mainnet wallets or merchant tooling from using this client; set it once, deliberately,
+     * wherever real production traffic is intended.
+     */
+    allowMainnetWrites?: boolean;
+}
+/** Amount accepted by ergonomic methods: a human CKB amount, or an already-hex shannon amount. */
+export type AmountLike = number | HexString;
+/**
+ * Ergonomic TypeScript client for the Fiber Network Node (FNN) JSON-RPC.
+ *
+ * ```ts
+ * const fiber = new FiberClient("http://127.0.0.1:8227");
+ * await fiber.info();
+ * await fiber.connectPeer({ address: "/ip4/.../p2p/..." });
+ * await fiber.openChannel({ pubkey, fundingAmount: 500 });
+ * const { invoice_address } = await fiber.createInvoice({ amount: 10, description: "coffee" });
+ * await fiber.payInvoice(invoice_address);
+ * await fiber.listChannels();
+ * ```
+ */
+export declare class FiberClient {
+    private readonly nodeUrl;
+    private readonly authToken?;
+    private readonly timeoutMs;
+    private readonly defaultCurrency;
+    private readonly network?;
+    private readonly allowMainnetWrites;
+    constructor(config: string | FiberClientConfig);
+    info(): Promise<NodeInfo>;
+    listPeers(): Promise<PeerInfo[]>;
+    connectPeer(params: ConnectPeerParams): Promise<void>;
+    disconnectPeer(params: DisconnectPeerParams | HexString): Promise<void>;
+    openChannel(params: Omit<OpenChannelParams, "fundingAmount"> & {
+        fundingAmount: AmountLike;
+    }): Promise<OpenChannelResult>;
+    acceptChannel(params: Omit<AcceptChannelParams, "fundingAmount"> & {
+        fundingAmount: AmountLike;
+    }): Promise<AcceptChannelResult>;
+    abandonChannel(params: AbandonChannelParams | HexString): Promise<void>;
+    listChannels(params?: ListChannelsParams): Promise<Channel[]>;
+    shutdownChannel(params: ShutdownChannelParams): Promise<void>;
+    updateChannel(params: UpdateChannelParams): Promise<void>;
+    createInvoice(params: Omit<NewInvoiceParams, "amount" | "currency"> & {
+        amount: AmountLike;
+        currency?: InvoiceCurrency;
+    }): Promise<NewInvoiceResult>;
+    parseInvoice(invoice: string): Promise<CkbInvoice>;
+    getInvoice(paymentHash: HexString): Promise<GetInvoiceResult>;
+    cancelInvoice(params: CancelInvoiceParams | HexString): Promise<void>;
+    settleInvoice(params: SettleInvoiceParams): Promise<void>;
+    sendPayment(params: Omit<SendPaymentParams, "amount"> & {
+        amount?: AmountLike;
+    }): Promise<PaymentResult>;
+    /** Convenience wrapper: pay an encoded invoice (as returned by `createInvoice`'s `invoice_address`). */
+    payInvoice(invoice: string, opts?: Omit<SendPaymentParams, "invoice" | "targetPubkey">): Promise<PaymentResult>;
+    getPayment(params: GetPaymentParams | HexString): Promise<PaymentResult>;
+    listPayments(params?: ListPaymentsParams): Promise<PaymentResult[]>;
+    private guardWriteOp;
+    private call;
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,14 @@
+import { FiberError } from "./errors";
+import type { PaymentResult } from "./types/payment";
+export type DiagnosisCode = "INSUFFICIENT_LIQUIDITY" | "ROUTE_NOT_FOUND" | "PEER_NOT_CONNECTED" | "PEER_UNREACHABLE" | "INVOICE_EXPIRED" | "INVOICE_ALREADY_PAID" | "INVOICE_CANCELLED" | "INVALID_PARAMS" | "TIMEOUT" | "UNKNOWN";
+export interface Diagnosis {
+    code: DiagnosisCode;
+    /** Plain-English explanation of what likely happened. */
+    summary: string;
+    /** A concrete next step to try. */
+    suggestion: string;
+}
+/** Turns a `FiberError` into a structured, actionable diagnosis for logs, CLIs, or UIs. */
+export declare function diagnose(error: FiberError): Diagnosis;
+/** Diagnoses a `Failed` payment's `failed_error` field. Returns `null` for non-failed payments. */
+export declare function diagnosePayment(payment: PaymentResult): Diagnosis | null;

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export type FiberErrorCode = "NETWORK_ERROR" | "RPC_ERROR" | "INVALID_RESPONSE" | "REQUEST_TIMEOUT" | "MAINNET_WRITE_BLOCKED";
+export declare class FiberError extends Error {
+    readonly code: FiberErrorCode;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(code: FiberErrorCode, message: string, context?: Record<string, unknown> | undefined);
+    static is(err: unknown): err is FiberError;
+}

package/dist/events.d.ts

@@ -0,0 +1,64 @@
+import { type Diagnosis } from "./diagnostics";
+import type { FiberClient } from "./client";
+import type { Channel } from "./types/channel";
+import type { PaymentResult } from "./types/payment";
+export type FiberEvent = {
+    type: "channel.opened";
+    channel: Channel;
+} | {
+    type: "channel.updated";
+    channel: Channel;
+} | {
+    type: "channel.closed";
+    channel: Channel;
+} | {
+    type: "payment.created";
+    payment: PaymentResult;
+} | {
+    type: "payment.updated";
+    payment: PaymentResult;
+} | {
+    type: "payment.succeeded";
+    payment: PaymentResult;
+} | {
+    type: "payment.failed";
+    payment: PaymentResult;
+    diagnosis: Diagnosis | null;
+};
+export interface FiberEventClientConfig {
+    client: FiberClient;
+    /** How often to poll `listChannels`/`listPayments` for changes, in ms. Default: 1000. */
+    pollIntervalMs?: number;
+    /**
+     * Called when a poll cycle fails (transient RPC/network error). Polling continues on the
+     * next interval regardless — a single flaky call must never take down a long-running
+     * consumer (the inspector server, a CI test run). Default: swallowed silently.
+     */
+    onError?: (error: unknown) => void;
+}
+/**
+ * FNN's RPC exposes no server-push subscription channel for clients (the node's WebSocket
+ * support is for the Fiber peer-to-peer transport, not for RPC event delivery). This client
+ * approximates live events by polling `listChannels`/`listPayments` on an interval and
+ * diffing snapshots, so downstream consumers (the inspector UI, test-client assertions) can
+ * still subscribe to a typed event stream.
+ */
+export declare class FiberEventClient {
+    private readonly client;
+    private readonly pollIntervalMs;
+    private readonly onError;
+    private readonly handlers;
+    private timer;
+    private lastChannels;
+    private lastPayments;
+    private polling;
+    constructor(config: FiberEventClientConfig);
+    start(): void;
+    stop(): void;
+    /** Subscribes to an event type. Returns an unsubscribe function. */
+    on(type: FiberEvent["type"], handler: (event: FiberEvent) => void): () => void;
+    private emit;
+    private poll;
+    private pollChannels;
+    private pollPayments;
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { FiberClient } from "./client";
+export type { FiberClientConfig, AmountLike } from "./client";
+export { FiberEventClient } from "./events";
+export type { FiberEvent, FiberEventClientConfig } from "./events";
+export { FiberError } from "./errors";
+export type { FiberErrorCode } from "./errors";
+export { diagnose, diagnosePayment } from "./diagnostics";
+export type { Diagnosis, DiagnosisCode } from "./diagnostics";
+export { evaluateAlerts } from "./alerts";
+export type { Alert, AlertCode, AlertRules, AlertSeverity, AlertSnapshot } from "./alerts";
+export { ckbToShannonHex, shannonHexToCkb, formatAmount, toHex, fromHex } from "./utils";
+export type { HexString, Script, Ckb } from "./types/common";
+export type { NetworkMode } from "./types/network";
+export type { NodeInfo, PeerInfo, ConnectPeerParams, DisconnectPeerParams, PeerAddressType, UdtCfgInfo, UdtCellDep } from "./types/node";
+export type { Channel, ChannelState, OpenChannelParams, OpenChannelResult, AcceptChannelParams, AcceptChannelResult, ListChannelsParams, ListChannelsResult, AbandonChannelParams, ShutdownChannelParams, UpdateChannelParams, } from "./types/channel";
+export type { CkbInvoice, CkbInvoiceData, InvoiceCurrency, InvoiceStatus, HashAlgorithm, NewInvoiceParams, NewInvoiceResult, GetInvoiceResult, ParseInvoiceParams, ParseInvoiceResult, CancelInvoiceParams, SettleInvoiceParams, } from "./types/invoice";
+export type { PaymentStatus, PaymentResult, SendPaymentParams, HopHint, GetPaymentParams, ListPaymentsParams, ListPaymentsResult, } from "./types/payment";

package/dist/index.js

@@ -0,0 +1,490 @@
+// src/errors.ts
+var FiberError = class _FiberError extends Error {
+  constructor(code, message, context) {
+    super(message);
+    this.code = code;
+    this.context = context;
+    this.name = "FiberError";
+  }
+  code;
+  context;
+  static is(err) {
+    return err instanceof _FiberError;
+  }
+};
+
+// src/utils.ts
+var SHANNONS_PER_CKB = 100000000n;
+function ckbToShannonHex(ckb) {
+  if (!Number.isFinite(ckb) || ckb < 0) {
+    throw new RangeError(`ckbToShannonHex: amount must be a non-negative finite number, got ${ckb}`);
+  }
+  const shannons = BigInt(Math.round(ckb * Number(SHANNONS_PER_CKB)));
+  return toHex(shannons);
+}
+function shannonHexToCkb(hex) {
+  const shannons = fromHex(hex);
+  return Number(shannons) / Number(SHANNONS_PER_CKB);
+}
+function formatAmount(hex, unit = "CKB") {
+  if (unit === "shannon") {
+    return `${fromHex(hex).toString()} shannon`;
+  }
+  return `${shannonHexToCkb(hex)} CKB`;
+}
+function toHex(value) {
+  const big = typeof value === "bigint" ? value : BigInt(value);
+  if (big < 0n) {
+    throw new RangeError(`toHex: value must be non-negative, got ${big}`);
+  }
+  return `0x${big.toString(16)}`;
+}
+function fromHex(hex) {
+  return BigInt(hex);
+}
+
+// src/client.ts
+function resolveAmount(amount) {
+  return typeof amount === "number" ? ckbToShannonHex(amount) : amount;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function camelToSnakeKey(key) {
+  return key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+function toWireParams(value) {
+  if (Array.isArray(value)) {
+    return value.map(toWireParams);
+  }
+  if (isPlainObject(value)) {
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+      if (val === void 0) continue;
+      result[camelToSnakeKey(key)] = toWireParams(val);
+    }
+    return result;
+  }
+  if (typeof value === "number") {
+    return toHex(value);
+  }
+  return value;
+}
+var FiberClient = class {
+  nodeUrl;
+  authToken;
+  timeoutMs;
+  defaultCurrency;
+  network;
+  allowMainnetWrites;
+  constructor(config) {
+    const resolved = typeof config === "string" ? { nodeUrl: config } : config;
+    this.nodeUrl = resolved.nodeUrl;
+    this.authToken = resolved.authToken;
+    this.timeoutMs = resolved.timeoutMs ?? 3e4;
+    this.defaultCurrency = resolved.defaultCurrency ?? "Fibt";
+    this.network = resolved.network;
+    this.allowMainnetWrites = resolved.allowMainnetWrites ?? false;
+  }
+  // ── Node ──────────────────────────────────────────────────
+  info() {
+    return this.call("node_info", []);
+  }
+  async listPeers() {
+    const result = await this.call("list_peers", []);
+    return result.peers;
+  }
+  async connectPeer(params) {
+    await this.call("connect_peer", [toWireParams(params)]);
+  }
+  async disconnectPeer(params) {
+    const wire = typeof params === "string" ? { pubkey: params } : params;
+    await this.call("disconnect_peer", [toWireParams(wire)]);
+  }
+  // ── Channels ──────────────────────────────────────────────
+  openChannel(params) {
+    this.guardWriteOp("openChannel");
+    return this.call("open_channel", [
+      toWireParams({ ...params, fundingAmount: resolveAmount(params.fundingAmount) })
+    ]);
+  }
+  acceptChannel(params) {
+    this.guardWriteOp("acceptChannel");
+    return this.call("accept_channel", [
+      toWireParams({ ...params, fundingAmount: resolveAmount(params.fundingAmount) })
+    ]);
+  }
+  async abandonChannel(params) {
+    this.guardWriteOp("abandonChannel");
+    const wire = typeof params === "string" ? { channelId: params } : params;
+    await this.call("abandon_channel", [toWireParams(wire)]);
+  }
+  async listChannels(params = {}) {
+    const result = await this.call("list_channels", [toWireParams(params)]);
+    return result.channels;
+  }
+  async shutdownChannel(params) {
+    this.guardWriteOp("shutdownChannel");
+    await this.call("shutdown_channel", [toWireParams(params)]);
+  }
+  async updateChannel(params) {
+    await this.call("update_channel", [toWireParams(params)]);
+  }
+  // ── Invoices ──────────────────────────────────────────────
+  createInvoice(params) {
+    return this.call("new_invoice", [
+      toWireParams({
+        ...params,
+        amount: resolveAmount(params.amount),
+        currency: params.currency ?? this.defaultCurrency
+      })
+    ]);
+  }
+  async parseInvoice(invoice) {
+    const result = await this.call("parse_invoice", [{ invoice }]);
+    return result.invoice;
+  }
+  getInvoice(paymentHash) {
+    return this.call("get_invoice", [{ payment_hash: paymentHash }]);
+  }
+  async cancelInvoice(params) {
+    const wire = typeof params === "string" ? { paymentHash: params } : params;
+    await this.call("cancel_invoice", [toWireParams(wire)]);
+  }
+  async settleInvoice(params) {
+    await this.call("settle_invoice", [toWireParams(params)]);
+  }
+  // ── Payments ──────────────────────────────────────────────
+  sendPayment(params) {
+    this.guardWriteOp("sendPayment");
+    return this.call("send_payment", [
+      toWireParams({
+        ...params,
+        amount: params.amount === void 0 ? void 0 : resolveAmount(params.amount)
+      })
+    ]);
+  }
+  /** Convenience wrapper: pay an encoded invoice (as returned by `createInvoice`'s `invoice_address`). */
+  payInvoice(invoice, opts = {}) {
+    return this.sendPayment({ ...opts, invoice });
+  }
+  getPayment(params) {
+    const wire = typeof params === "string" ? { paymentHash: params } : params;
+    return this.call("get_payment", [toWireParams(wire)]);
+  }
+  async listPayments(params = {}) {
+    const result = await this.call("list_payments", [toWireParams(params)]);
+    return result.payments;
+  }
+  // ── Internal ──────────────────────────────────────────────
+  guardWriteOp(method) {
+    if (this.network === "mainnet" && !this.allowMainnetWrites) {
+      throw new FiberError(
+        "MAINNET_WRITE_BLOCKED",
+        `${method}() is blocked because this client is configured for network: "mainnet". If this is intentional production traffic, set allowMainnetWrites: true in the FiberClient config.`,
+        { method }
+      );
+    }
+  }
+  async call(method, params) {
+    let response;
+    try {
+      response = await fetch(this.nodeUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.authToken ? { Authorization: `Bearer ${this.authToken}` } : {}
+        },
+        body: JSON.stringify({ jsonrpc: "2.0", id: Date.now(), method, params }),
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (err) {
+      if (err instanceof Error && err.name === "TimeoutError") {
+        throw new FiberError("REQUEST_TIMEOUT", `RPC call to ${method} exceeded ${this.timeoutMs}ms`, { method });
+      }
+      throw new FiberError("NETWORK_ERROR", `Failed to reach ${this.nodeUrl}: ${err.message}`, {
+        method,
+        cause: err
+      });
+    }
+    if (!response.ok) {
+      throw new FiberError("NETWORK_ERROR", `HTTP ${response.status} from ${this.nodeUrl}`, {
+        method,
+        status: response.status
+      });
+    }
+    let data;
+    try {
+      data = await response.json();
+    } catch (err) {
+      throw new FiberError("INVALID_RESPONSE", `Non-JSON response from ${this.nodeUrl}`, { method, cause: err });
+    }
+    if (data.error) {
+      throw new FiberError("RPC_ERROR", data.error.message, {
+        method,
+        rpcCode: data.error.code,
+        rpcData: data.error.data
+      });
+    }
+    return data.result;
+  }
+};
+
+// src/diagnostics.ts
+var PATTERNS = [
+  {
+    code: "INSUFFICIENT_LIQUIDITY",
+    test: /insufficient|liquidity|not enough balance|exceeds.*balance/i,
+    summary: "The route has capacity in total, but not enough usable balance in the direction this payment needs to flow.",
+    suggestion: "Reduce the payment amount, open a larger channel, or rebalance existing channels toward the recipient."
+  },
+  {
+    code: "ROUTE_NOT_FOUND",
+    test: /no route|route.*not found|routing.*fail|unable to find a route/i,
+    summary: "No path could be found from this node to the target through the currently known network graph.",
+    suggestion: "Confirm the target node has at least one public channel, or connect directly and open a channel to it."
+  },
+  {
+    code: "PEER_NOT_CONNECTED",
+    test: /peer.*not (found|connected)|not connected to peer/i,
+    summary: "The RPC call targets a peer this node hasn't connected to yet.",
+    suggestion: "Call connectPeer() with the peer's multiaddr or pubkey before retrying this operation."
+  },
+  {
+    code: "PEER_UNREACHABLE",
+    test: /connection refused|dial.*fail|unreachable|timed out.*connect/i,
+    summary: "The node could not establish a network connection to the peer's address.",
+    suggestion: "Check the peer's multiaddr/port and confirm it's online and reachable from this node."
+  },
+  {
+    code: "INVOICE_EXPIRED",
+    test: /invoice.*expired|expired.*invoice/i,
+    summary: "The invoice's expiry window has passed.",
+    suggestion: "Ask the recipient to generate a new invoice with createInvoice()."
+  },
+  {
+    code: "INVOICE_ALREADY_PAID",
+    test: /already paid|invoice.*paid/i,
+    summary: "This invoice has already been settled.",
+    suggestion: "No action needed \u2014 check getPayment()/getInvoice() for the existing settlement."
+  },
+  {
+    code: "INVOICE_CANCELLED",
+    test: /invoice.*cancel/i,
+    summary: "This invoice was cancelled and can no longer be paid.",
+    suggestion: "Ask the recipient to generate a new invoice."
+  },
+  {
+    code: "INVALID_PARAMS",
+    // "invalid pubkey '...': malformed public key" is a confirmed live FNN error string.
+    test: /missing field|invalid params|invalid type|invalid \w+|malformed|expected/i,
+    summary: "The RPC call was rejected because a parameter was missing, malformed, or the wrong type.",
+    suggestion: "Inspect the error's context.rpcData for the exact field FNN rejected."
+  }
+];
+function diagnose(error) {
+  if (error.code === "REQUEST_TIMEOUT") {
+    return {
+      code: "TIMEOUT",
+      summary: "The RPC call exceeded its timeout before the node responded.",
+      suggestion: "Retry with a longer timeoutMs, or check whether the node is under heavy load."
+    };
+  }
+  const haystack = `${error.message} ${JSON.stringify(error.context?.rpcData ?? "")}`;
+  const match = PATTERNS.find((pattern) => pattern.test.test(haystack));
+  if (match) {
+    return { code: match.code, summary: match.summary, suggestion: match.suggestion };
+  }
+  return {
+    code: "UNKNOWN",
+    summary: error.message,
+    suggestion: "No known pattern matched this error; inspect error.context for the raw RPC response."
+  };
+}
+function diagnosePayment(payment) {
+  if (payment.status !== "Failed" || !payment.failed_error) return null;
+  return diagnose(new FiberError("RPC_ERROR", payment.failed_error));
+}
+
+// src/events.ts
+var FiberEventClient = class {
+  client;
+  pollIntervalMs;
+  onError;
+  handlers = /* @__PURE__ */ new Map();
+  timer = null;
+  lastChannels = /* @__PURE__ */ new Map();
+  lastPayments = /* @__PURE__ */ new Map();
+  polling = false;
+  constructor(config) {
+    this.client = config.client;
+    this.pollIntervalMs = config.pollIntervalMs ?? 1e3;
+    this.onError = config.onError ?? (() => {
+    });
+  }
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => void this.poll(), this.pollIntervalMs);
+    void this.poll();
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  /** Subscribes to an event type. Returns an unsubscribe function. */
+  on(type, handler) {
+    if (!this.handlers.has(type)) {
+      this.handlers.set(type, /* @__PURE__ */ new Set());
+    }
+    this.handlers.get(type).add(handler);
+    return () => this.handlers.get(type)?.delete(handler);
+  }
+  emit(event) {
+    for (const handler of this.handlers.get(event.type) ?? []) {
+      handler(event);
+    }
+  }
+  async poll() {
+    if (this.polling) return;
+    this.polling = true;
+    try {
+      await Promise.all([this.pollChannels(), this.pollPayments()]);
+    } catch (err) {
+      this.onError(err);
+    } finally {
+      this.polling = false;
+    }
+  }
+  async pollChannels() {
+    const channels = await this.client.listChannels({ includeClosed: true });
+    const seen = /* @__PURE__ */ new Set();
+    for (const channel of channels) {
+      seen.add(channel.channel_id);
+      const previous = this.lastChannels.get(channel.channel_id);
+      const state = channelStateName(channel);
+      if (!previous) {
+        this.emit({ type: "channel.opened", channel });
+      } else if (channelStateName(previous) !== state) {
+        this.emit({ type: state === "Closed" ? "channel.closed" : "channel.updated", channel });
+      }
+      this.lastChannels.set(channel.channel_id, channel);
+    }
+    for (const [id, channel] of this.lastChannels) {
+      if (!seen.has(id)) {
+        this.emit({ type: "channel.closed", channel });
+        this.lastChannels.delete(id);
+      }
+    }
+  }
+  async pollPayments() {
+    const payments = await this.client.listPayments({ limit: 50 });
+    for (const payment of payments) {
+      const previous = this.lastPayments.get(payment.payment_hash);
+      if (!previous) {
+        this.emit({ type: "payment.created", payment });
+      } else if (previous.status !== payment.status) {
+        this.emit({ type: "payment.updated", payment });
+        if (payment.status === "Success") this.emit({ type: "payment.succeeded", payment });
+        if (payment.status === "Failed") {
+          this.emit({ type: "payment.failed", payment, diagnosis: diagnosePayment(payment) });
+        }
+      }
+      this.lastPayments.set(payment.payment_hash, payment);
+    }
+  }
+};
+function channelStateName(channel) {
+  return channel.state.state_name;
+}
+
+// src/alerts.ts
+var DEFAULT_ALERT_RULES = {
+  requirePeers: true,
+  requireReadyChannels: true,
+  minLocalBalanceCkb: 1,
+  includeFailedPayments: true
+};
+function evaluateAlerts(snapshot, rules = {}) {
+  const resolved = { ...DEFAULT_ALERT_RULES, ...rules };
+  const alerts = [];
+  const nodeId = snapshot.nodeId;
+  if (snapshot.nodeError || !snapshot.node) {
+    return [
+      {
+        code: "NODE_UNREACHABLE",
+        severity: "critical",
+        nodeId,
+        summary: `Node${nodeId ? ` "${nodeId}"` : ""} is not reachable over RPC.`,
+        suggestion: "Confirm the FNN process is running and that the RPC URL, port, and auth settings are correct."
+      }
+    ];
+  }
+  const peers = snapshot.peers ?? [];
+  if (resolved.requirePeers && peers.length === 0 && fromHex(snapshot.node.peers_count) === 0n) {
+    alerts.push({
+      code: "ZERO_PEERS",
+      severity: "warning",
+      nodeId,
+      summary: `Node${nodeId ? ` "${nodeId}"` : ""} has no connected peers.`,
+      suggestion: "Connect at least one reachable Fiber peer before opening channels or testing routed payments."
+    });
+  }
+  const channels = snapshot.channels ?? [];
+  const readyChannels = channels.filter((channel) => channel.state.state_name === "ChannelReady");
+  if (resolved.requireReadyChannels && readyChannels.length === 0) {
+    alerts.push({
+      code: "NO_READY_CHANNELS",
+      severity: "warning",
+      nodeId,
+      summary: `Node${nodeId ? ` "${nodeId}"` : ""} has no ready channels.`,
+      suggestion: "Open a channel and wait until it reaches ChannelReady before testing payments."
+    });
+  }
+  for (const channel of readyChannels) {
+    const localBalance = shannonHexToCkb(channel.local_balance);
+    if (localBalance < resolved.minLocalBalanceCkb) {
+      alerts.push({
+        code: "LOW_LOCAL_BALANCE",
+        severity: "warning",
+        nodeId,
+        channelId: channel.channel_id,
+        summary: `Channel ${shortId(channel.channel_id)} has only ${localBalance} CKB of outbound balance.`,
+        suggestion: "Rebalance the channel, reduce payment size, or open a channel with more local liquidity."
+      });
+    }
+  }
+  if (resolved.includeFailedPayments) {
+    for (const payment of snapshot.payments ?? []) {
+      if (payment.status !== "Failed") continue;
+      const diagnosis = diagnosePayment(payment);
+      alerts.push({
+        code: "PAYMENT_FAILED",
+        severity: "critical",
+        nodeId,
+        paymentHash: payment.payment_hash,
+        diagnosis,
+        summary: diagnosis?.summary ?? `Payment ${shortId(payment.payment_hash)} failed.`,
+        suggestion: diagnosis?.suggestion ?? "Inspect the raw failed_error field and retry after correcting the route or invoice."
+      });
+    }
+  }
+  return alerts;
+}
+function shortId(value) {
+  return value.length > 14 ? `${value.slice(0, 12)}...` : value;
+}
+export {
+  FiberClient,
+  FiberError,
+  FiberEventClient,
+  ckbToShannonHex,
+  diagnose,
+  diagnosePayment,
+  evaluateAlerts,
+  formatAmount,
+  fromHex,
+  shannonHexToCkb,
+  toHex
+};

package/dist/types/channel.d.ts

@@ -0,0 +1,86 @@
+import type { HexString, Script } from "./common";
+export interface OpenChannelParams {
+    /** Pubkey of the peer to open a channel with. The peer must already be connected via `connectPeer`. */
+    pubkey: HexString;
+    /** Funding amount in shannons (hex) or CKB (number) — ergonomic methods accept CKB and convert. */
+    fundingAmount: HexString;
+    /** Broadcast to the network so it can forward TLCs. Default: true. */
+    public?: boolean;
+    /** One-way channel: not broadcast, can only send payments in one direction. Default: false. */
+    oneWay?: boolean;
+    fundingUdtTypeScript?: Script;
+    shutdownScript?: Script;
+    commitmentDelayEpoch?: HexString;
+    commitmentFeeRate?: HexString;
+    fundingFeeRate?: HexString;
+    tlcExpiryDelta?: HexString;
+    tlcMinValue?: HexString;
+    tlcFeeProportionalMillionths?: HexString;
+    maxTlcValueInFlight?: HexString;
+    maxTlcNumberInFlight?: HexString;
+}
+export interface OpenChannelResult {
+    temporary_channel_id: HexString;
+}
+export interface AcceptChannelParams {
+    temporaryChannelId: HexString;
+    fundingAmount: HexString;
+    shutdownScript?: Script;
+    maxTlcValueInFlight?: HexString;
+}
+export interface AcceptChannelResult {
+    channel_id: HexString;
+}
+export interface ListChannelsParams {
+    pubkey?: HexString;
+    includeClosed?: boolean;
+    onlyPending?: boolean;
+}
+/**
+ * PascalCase per FNN's serde convention, confirmed live via `ChannelReady`. The pending
+ * states are named per `list_channels --only-pending`'s help text ("negotiating,
+ * collaborating on funding tx, signing, awaiting tx signatures, awaiting channel ready").
+ */
+export type ChannelState = "NegotiatingFunding" | "CollaboratingFundingTx" | "SigningCommitment" | "AwaitingTxSignatures" | "AwaitingChannelReady" | "ChannelReady" | "ShuttingDown" | "Closed";
+/**
+ * `list_channels` entry. `channel_id`, `channel_outpoint`, `state.state_name`,
+ * `local_balance`, and `remote_balance` are confirmed against a real funded testnet
+ * channel; the rest mirror `open_channel`'s snake_case parameter surface and should be
+ * spot-checked as they come up.
+ */
+export interface Channel {
+    channel_id: HexString;
+    channel_outpoint: HexString;
+    latest_commitment_transaction_hash?: HexString;
+    peer_id?: HexString;
+    state: {
+        state_name: ChannelState;
+        state_flags?: string[];
+    };
+    local_balance: HexString;
+    remote_balance: HexString;
+    offered_tlc_balance?: HexString;
+    received_tlc_balance?: HexString;
+    is_public?: boolean;
+    funding_udt_type_script?: Script;
+    created_at?: HexString;
+}
+export interface ListChannelsResult {
+    channels: Channel[];
+}
+export interface AbandonChannelParams {
+    channelId: HexString;
+}
+export interface ShutdownChannelParams {
+    channelId: HexString;
+    closeScript?: Script;
+    feeRate?: HexString;
+    force?: boolean;
+}
+export interface UpdateChannelParams {
+    channelId: HexString;
+    enabled?: boolean;
+    tlcExpiryDelta?: HexString;
+    tlcMinimumValue?: HexString;
+    tlcFeeProportionalMillionths?: HexString;
+}

package/dist/types/common.d.ts

@@ -0,0 +1,10 @@
+/** A `0x`-prefixed hex string, as returned by FNN's JSON-RPC for hashes, pubkeys, and amounts. */
+export type HexString = `0x${string}`;
+/** A CKB script (lock or type). */
+export interface Script {
+    code_hash: HexString;
+    hash_type: "type" | "data" | "data1" | "data2";
+    args: HexString;
+}
+/** Human-readable CKB amount, as accepted by the ergonomic client methods (converted to shannon hex on the wire). */
+export type Ckb = number;

package/dist/types/invoice.d.ts

@@ -0,0 +1,69 @@
+import type { HexString, Script } from "./common";
+/** Fiber Bitcoin-style bech32m prefixes: mainnet, testnet, devnet. */
+export type InvoiceCurrency = "Fibb" | "Fibt" | "Fibd";
+export type HashAlgorithm = "Sha256" | "Ckbhash";
+export interface NewInvoiceParams {
+    /** Amount in shannons (hex) or CKB (number) — ergonomic methods accept CKB and convert. */
+    amount: HexString;
+    currency: InvoiceCurrency;
+    description?: string;
+    /** If set, `paymentHash` must be absent. If both are absent, a random preimage is generated. */
+    paymentPreimage?: HexString;
+    /** Hold invoice: hash is known, preimage is revealed later via `settleInvoice`. */
+    paymentHash?: HexString;
+    /** Expiry in seconds. */
+    expiry?: number;
+    fallbackAddress?: string;
+    /** Final HTLC timeout in ms. Min 16 hours, max 14 days. */
+    finalExpiryDelta?: number;
+    udtTypeScript?: Script;
+    hashAlgorithm?: HashAlgorithm;
+    allowMpp?: boolean;
+    allowTrampolineRouting?: boolean;
+}
+interface InvoiceAttrDescription {
+    description: string;
+}
+interface InvoiceAttrExpiry {
+    final_htlc_minimum_expiry_delta: HexString;
+}
+interface InvoiceAttrPayee {
+    payee_public_key: HexString;
+}
+type InvoiceAttr = InvoiceAttrDescription | InvoiceAttrExpiry | InvoiceAttrPayee | Record<string, unknown>;
+export interface CkbInvoiceData {
+    attrs: InvoiceAttr[];
+    payment_hash: HexString;
+    timestamp: HexString;
+}
+export interface CkbInvoice {
+    amount: HexString;
+    currency: InvoiceCurrency;
+    data: CkbInvoiceData;
+    signature: string;
+}
+export interface NewInvoiceResult {
+    invoice: CkbInvoice;
+    invoice_address: string;
+}
+/** `Open` confirmed live; `Cancelled`/`Paid`/`Expired` per the RPC's documented invoice lifecycle. */
+export type InvoiceStatus = "Open" | "Cancelled" | "Paid" | "Expired";
+export interface GetInvoiceResult {
+    invoice: CkbInvoice;
+    invoice_address: string;
+    status: InvoiceStatus;
+}
+export interface ParseInvoiceParams {
+    invoice: string;
+}
+export interface ParseInvoiceResult {
+    invoice: CkbInvoice;
+}
+export interface CancelInvoiceParams {
+    paymentHash: HexString;
+}
+export interface SettleInvoiceParams {
+    paymentHash: HexString;
+    paymentPreimage: HexString;
+}
+export {};

package/dist/types/network.d.ts

@@ -0,0 +1,2 @@
+/** Which Fiber network a client is pointed at. Drives `FiberClient`'s mainnet write-guard. */
+export type NetworkMode = "devnet" | "testnet" | "mainnet";

package/dist/types/node.d.ts

@@ -0,0 +1,55 @@
+import type { HexString, Script } from "./common";
+export interface UdtCellDep {
+    type_id?: Script;
+    cell_dep?: {
+        out_point: {
+            tx_hash: HexString;
+            index: HexString;
+        };
+        dep_type: "code" | "dep_group";
+    };
+}
+export interface UdtCfgInfo {
+    name: string;
+    script: Script;
+    auto_accept_amount?: HexString;
+    cell_deps: UdtCellDep[];
+}
+/** Raw `node_info` RPC result. All amount fields are hex-encoded shannons. */
+export interface NodeInfo {
+    version: string;
+    commit_hash: string;
+    pubkey: HexString;
+    features: string[];
+    node_name: string | null;
+    addresses: string[];
+    chain_hash: HexString;
+    open_channel_auto_accept_min_ckb_funding_amount: HexString;
+    auto_accept_channel_ckb_funding_amount: HexString;
+    default_funding_lock_script: Script;
+    tlc_expiry_delta: HexString;
+    tlc_min_value: HexString;
+    tlc_fee_proportional_millionths: HexString;
+    channel_count: HexString;
+    pending_channel_count: HexString;
+    peers_count: HexString;
+    udt_cfg_infos: UdtCfgInfo[];
+}
+/** Raw `list_peers` RPC result entry. */
+export interface PeerInfo {
+    pubkey: HexString;
+    address: string;
+}
+export type PeerAddressType = "tcp" | "ws" | "wss";
+export interface ConnectPeerParams {
+    /** Multiaddr string of the peer. Either `address` or `pubkey` must be provided. */
+    address?: string;
+    /** Peer pubkey; the node resolves the address from locally synced graph data. */
+    pubkey?: HexString;
+    /** Whether to persist the peer address to the peer store. */
+    save?: boolean;
+    addrType?: PeerAddressType;
+}
+export interface DisconnectPeerParams {
+    pubkey: HexString;
+}

package/dist/types/payment.d.ts

@@ -0,0 +1,60 @@
+import type { HexString, Script } from "./common";
+export interface HopHint {
+    pubkey: HexString;
+    channelOutpoint: string;
+    feeRate: HexString;
+    tlcExpiryDelta: HexString;
+}
+export interface SendPaymentParams {
+    /** Pubkey of the payment target node. Obtainable via `info()` or `graph_nodes`. */
+    targetPubkey?: HexString;
+    /** Amount in shannons (hex) or CKB (number) for non-UDT payments. Defaults to the invoice amount if unset. */
+    amount?: HexString;
+    /** Hash used in the payment's HTLC. Required unless `keysend` or an invoice supplies one. */
+    paymentHash?: HexString;
+    finalTlcExpiryDelta?: number;
+    tlcExpiryLimit?: number;
+    /** Encoded invoice string (`invoice_address` from `createInvoice`). */
+    invoice?: string;
+    /** Payment timeout in seconds. */
+    timeout?: number;
+    maxFeeAmount?: HexString;
+    maxFeeRate?: number;
+    maxParts?: number;
+    trampolineHops?: HexString[];
+    keysend?: boolean;
+    udtTypeScript?: Script;
+    /** Allow a circular self-payment, used for channel rebalancing. */
+    allowSelfPayment?: boolean;
+    customRecords?: Record<string, HexString>;
+    hopHints?: HopHint[];
+    /** Dry-run: validate routing/fees without sending. */
+    dryRun?: boolean;
+}
+/**
+ * Payment lifecycle status. `Created` and `Success` confirmed against a real end-to-end
+ * testnet payment; `Inflight`/`Failed` per the RPC's `--status` filter on `list_payments`
+ * and standard Lightning-style payment lifecycles.
+ */
+export type PaymentStatus = "Created" | "Inflight" | "Success" | "Failed";
+/** Confirmed live: `payment_hash`, `status`, `created_at`, `fee`. */
+export interface PaymentResult {
+    payment_hash: HexString;
+    status: PaymentStatus;
+    created_at: HexString;
+    fee: HexString;
+    last_updated_at?: HexString;
+    failed_error?: string;
+}
+export interface GetPaymentParams {
+    paymentHash: HexString;
+}
+export interface ListPaymentsParams {
+    status?: PaymentStatus;
+    limit?: number;
+    after?: HexString;
+}
+export interface ListPaymentsResult {
+    payments: PaymentResult[];
+    last_cursor: HexString | null;
+}

package/dist/utils.d.ts

@@ -0,0 +1,9 @@
+import type { HexString } from "./types/common";
+/** Converts a human-readable CKB amount to a hex-encoded shannon amount, as FNN's RPC expects. */
+export declare function ckbToShannonHex(ckb: number): HexString;
+/** Converts a hex-encoded shannon amount from the RPC into a human-readable CKB amount. */
+export declare function shannonHexToCkb(hex: HexString): number;
+/** Formats a hex-encoded shannon amount for display, e.g. `formatAmount("0x5F5E10000", "CKB")` → `"100 CKB"`. */
+export declare function formatAmount(hex: HexString, unit?: "CKB" | "shannon"): string;
+export declare function toHex(value: bigint | number): HexString;
+export declare function fromHex(hex: HexString): bigint;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@fiber-dev-kit/core",
+  "version": "0.1.0-rc.0",
+  "description": "Network-aware TypeScript RPC client for the Fiber Network Node (FNN)",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/scisamir/fiber-dev-kit.git",
+    "directory": "core"
+  },
+  "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",
+    "rpc"
+  ],
+  "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"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.1",
+    "typescript": "^5.4.0",
+    "vitest": "^1.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}