librats 1.0.2 → 2.1.4

package/lib/index.d.ts

@@ -1,700 +1,275 @@
 /**
- * LibRats Node.js Bindings - TypeScript Definitions
- * 
- * High-performance peer-to-peer networking library with support for DHT, GossipSub,
- * file transfer, and more.
+ * TypeScript definitions for librats — Node.js bindings.
+ *
+ * A `RatsNode` is one librats node: secure transport (Noise XX over TCP or the
+ * library's reliable stream over UDP), a self-certifying peer id, and raw
+ * messaging on named channels. Everything else is an opt-in subsystem enabled
+ * BEFORE `start()`.
  */
 
-/**
- * Version information structure
- */
-export interface VersionInfo {
-  major: number;
-  minor: number;
-  patch: number;
-  build: number;
-}
-
-/**
- * Error codes returned by various operations
- */
-export enum ErrorCodes {
-  /** Operation completed successfully */
-  SUCCESS = 0,
-  /** Invalid client handle */
-  INVALID_HANDLE = -1,
-  /** Invalid parameter provided */
-  INVALID_PARAMETER = -2,
-  /** Client is not running */
-  NOT_RUNNING = -3,
-  /** Operation failed */
-  OPERATION_FAILED = -4,
-  /** Peer not found */
-  PEER_NOT_FOUND = -5,
-  /** Memory allocation error */
-  MEMORY_ALLOCATION = -6,
-  /** JSON parsing error */
-  JSON_PARSE = -7
-}
-
-/**
- * ICE connection states
- */
-export enum IceConnectionState {
-  NEW = 0,
-  GATHERING = 1,
-  CHECKING = 2,
-  CONNECTED = 3,
-  COMPLETED = 4,
-  FAILED = 5,
-  DISCONNECTED = 6,
-  CLOSED = 7
+/// <reference types="node" />
+
+declare module 'librats' {
+  /** Transport security selector (`rats_security_t`). */
+  export const Security: {
+    /** Noise XX, encrypted + authenticated (default). */
+    readonly NOISE: 0;
+    /** Unencrypted; ids exchanged in the clear. */
+    readonly PLAINTEXT: 1;
+  };
+
+  /**
+   * Which wire a peer connection runs on. Both carry the identical protocol and
+   * the identical encrypted handshake; they differ only in how the ordered,
+   * reliable byte stream underneath is obtained.
+   */
+  export const Transport: {
+    /** One kernel socket per peer. */
+    readonly TCP: 0;
+    /** Reliable stream over the shared UDP socket. */
+    readonly UDP: 1;
+  };
+
+  /** Bitmask flags used by `node.transports` and `node.peerTransports()`. */
+  export const TransportMask: {
+    readonly TCP: 0x1;
+    readonly UDP: 0x2;
+  };
+
+  /** What the mesh has shown about this node's own NAT. */
+  export const NatMapping: {
+    /** Not enough independent observations yet. */
+    readonly UNKNOWN: 0;
+    /** No NAT in the path. */
+    readonly OPEN: 1;
+    /** One external port for every peer — punchable. */
+    readonly ENDPOINT_INDEPENDENT: 2;
+    /** A fresh mapping per peer (symmetric) — not punchable. */
+    readonly ENDPOINT_DEPENDENT: 3;
+  };
+
+  /** Process-global log levels. */
+  export const LogLevel: {
+    readonly DEBUG: 0;
+    readonly INFO: 1;
+    readonly WARN: 2;
+    readonly ERROR: 3;
+  };
+
+  export type SecurityValue = 0 | 1;
+  export type TransportValue = 0 | 1;
+  export type NatMappingValue = 0 | 1 | 2 | 3;
+  export type LogLevelValue = 0 | 1 | 2 | 3;
+
+  /** Full node configuration; mirrors `rats_config_t`. Every field is optional. */
+  export interface RatsNodeConfig {
+    /** Inbound port shared by both transports; 0 = ephemeral. */
+    listenPort?: number;
+    /** `false` makes a dial-only node (no listener). Default `true`. */
+    enableListen?: boolean;
+    /** Bind address; omitted selects the `"::"` dual-stack wildcard. */
+    bindAddress?: string;
+    /** Default `Security.NOISE`. */
+    security?: SecurityValue;
+    /** Persistent state dir; omitted gives an ephemeral identity per run. */
+    dataDir?: string;
+    /** Handshake app id, e.g. `"myapp/1.0"`. Peers whose protocol differs cannot connect. */
+    protocol?: string;
+    /** Established-peer cap; 0 = unlimited. */
+    maxPeers?: number;
+    /** Accept and dial over TCP. Default `true`. */
+    enableTcp?: boolean;
+    /** Accept and dial over the datagram transport. Default `true`. */
+    enableUdp?: boolean;
+    /** Which transport a dial tries first. Default `Transport.UDP`. */
+    preferredTransport?: TransportValue;
+    /** Delay before the other transport is raced alongside; 0 disables. Default 1200. */
+    transportFallbackMs?: number;
+  }
+
+  export type PeerHandler = (peerId: string) => void;
+  export type MessageHandler = (peerId: string, data: Buffer) => void;
+  export type TopicHandler = (peerId: string, topic: string, data: Buffer) => void;
+  export type JsonHandler = (peerId: string, value: any) => void;
+  export type FileOfferHandler = (
+    peerId: string,
+    transferId: number,
+    name: string,
+    size: number,
+    isDirectory: boolean
+  ) => void;
+  export type FileProgressHandler = (
+    transferId: number,
+    peerId: string,
+    bytesTransferred: number,
+    totalBytes: number,
+    status: number
+  ) => void;
+  export type FileCompleteHandler = (
+    transferId: number,
+    success: boolean,
+    path: string
+  ) => void;
+
+  /** Library version components. */
+  export interface VersionInfo {
+    major: number;
+    minor: number;
+    patch: number;
+    build: number;
+  }
+
+  /**
+   * A librats node.
+   *
+   * Enable subsystems and register callbacks BEFORE `start()`. Failures throw an
+   * `Error` whose message is `librats: <CODE>`.
+   */
+  export class RatsNode {
+    /**
+     * @param portOrConfig listen port (0 = ephemeral) or a config object.
+     */
+    constructor(portOrConfig?: number | RatsNodeConfig);
+
+    // ---- lifecycle ----
+
+    /** Bring the node up: bind the listener and start enabled subsystems. */
+    start(): void;
+    /** Tear the node down and close all connections. Idempotent. */
+    stop(): void;
+    /** Release the native node; the instance is inert afterwards. */
+    destroy(): void;
+
+    // ---- identity / info ----
+
+    /** The bound listen port (resolved when 0 was requested). */
+    readonly listenPort: number;
+    /** Our self-certifying peer id (64-char lowercase hex). */
+    readonly localId: string | null;
+    /** The app protocol bound into the handshake, e.g. `"librats/1.0"`. */
+    readonly protocol: string | null;
+    /**
+     * Transports actually running, as a `TransportMask` bitmask. May be narrower
+     * than the config asked for. 0 before `start()` and after `stop()`.
+     */
+    readonly transports: number;
+
+    // ---- connections ----
+
+    /** Dial a peer. Non-blocking: success surfaces as `onPeerConnected`. */
+    connect(host: string, port: number): void;
+    /** Count of currently-connected peers. */
+    readonly peerCount: number;
+    /** Hex ids of currently-connected peers. */
+    readonly peerIds: string[];
+    /** Cap on established peers (0 = unlimited). Settable at any time. */
+    maxPeers: number;
+    /** Which wire a connected peer's link runs on, or `null` if not connected. */
+    peerTransport(peerId: string): TransportValue | null;
+    /**
+     * Transports a connected peer advertised, as a `TransportMask` bitmask, or
+     * `null` if not connected. 0 means the peer did not say (an older build).
+     */
+    peerTransports(peerId: string): number | null;
+
+    // ---- raw channel messaging ----
+
+    /** Send raw bytes on a named channel to one peer. */
+    send(peerId: string, channel: string, data: string | Buffer): void;
+    /** Broadcast raw bytes on a named channel to every connected peer. */
+    broadcast(channel: string, data: string | Buffer): void;
+    /** Register a handler for a named channel. Additive; register before `start()`. */
+    on(channel: string, handler: MessageHandler): void;
+
+    // ---- peer events (register before start) ----
+
+    onPeerConnected(handler: PeerHandler): void;
+    onPeerDisconnected(handler: PeerHandler): void;
+
+    // ---- discovery (enable before start) ----
+
+    /** Enable DHT discovery. `discoveryKey` defaults to the node's protocol. */
+    enableDht(dhtPort?: number, discoveryKey?: string): void;
+    /** Enable local-network mDNS discovery. */
+    enableMdns(): void;
+
+    // ---- NAT traversal (enable before start) ----
+
+    /** Enable automatic NAT port forwarding for the listen port. */
+    enablePortMapping(enableUpnp?: boolean, enableNatpmp?: boolean): void;
+    /**
+     * Enable UDP hole punching. `serveAsRelay` (default `true`) also carries
+     * other peers' rendezvous — a mesh in which nobody relays cannot punch.
+     */
+    enableHolePunch(serveAsRelay?: boolean): void;
+    /**
+     * Try to reach a peer by punching. Non-blocking: success arrives as an
+     * ordinary `onPeerConnected`.
+     */
+    punchPeer(peerId: string): void;
+    /** A `NatMapping` value describing this node's own NAT. */
+    readonly natMapping: NatMappingValue;
+
+    // ---- pub/sub (enable before start) ----
+
+    enablePubsub(): void;
+    subscribe(topic: string, handler: TopicHandler): void;
+    unsubscribe(topic: string): void;
+    publish(topic: string, data: string | Buffer): void;
+
+    // ---- typed JSON messaging (enable before start) ----
+
+    enableJson(): void;
+    /** Register an additive handler; the handler receives the parsed value. */
+    onJson(type: string, handler: JsonHandler): void;
+    /** Like `onJson`, but the handler is removed after it fires once. */
+    onceJson(type: string, handler: JsonHandler): void;
+    offJson(type: string): void;
+    /** `value` is serialized with `JSON.stringify` unless it is already a string. */
+    sendJson(peerId: string, type: string, value: any): void;
+    broadcastJson(type: string, value: any): void;
+
+    // ---- file transfer (enable + register callbacks before start) ----
+
+    enableFileTransfer(tempDir?: string): void;
+    onFileOffer(handler: FileOfferHandler): void;
+    onFileProgress(handler: FileProgressHandler): void;
+    onFileComplete(handler: FileCompleteHandler): void;
+    /** @returns the transfer id, or 0 on failure. */
+    sendFile(peerId: string, filePath: string): number;
+    /** @returns the transfer id, or 0 on failure. */
+    sendDirectory(peerId: string, dirPath: string): number;
+    /** `destPath` is the file path for a single file, else the destination directory. */
+    acceptFile(peerId: string, transferId: number, destPath: string): void;
+    rejectFile(peerId: string, transferId: number): void;
+    cancelFile(peerId: string, transferId: number): void;
+    pauseFile(peerId: string, transferId: number): void;
+    resumeFile(peerId: string, transferId: number): void;
+
+    // ---- liveness / reconnection (enable before start) ----
+
+    enablePing(): void;
+    /** Last measured RTT in ms, or -1 if unknown. */
+    peerRttMs(peerId: string): number;
+    enableReconnect(): void;
+    addReconnect(host: string, port: number): void;
+    removeReconnect(host: string, port: number): void;
+  }
+
+  // ---- library info (process-global) ----
+
+  /** Library version as a string, e.g. `"1.2.3"`. */
+  export function version(): string;
+  /** Library version components. */
+  export function versionInfo(): VersionInfo;
+  /** Git describe of the build, e.g. `"v1.2.3-4-gabcdef"`. */
+  export function gitDescribe(): string;
+  /** Packed ABI id as `(major << 16) | (minor << 8) | patch`. */
+  export function abi(): number;
+
+  // ---- process-global logging ----
+
+  export function setLogLevel(level: LogLevelValue): void;
+  /** Mirror logs to a file; omitted/empty disables file logging. */
+  export function setLogFile(path?: string): void;
 }
-
-/**
- * ICE gathering states
- */
-export enum IceGatheringState {
-  NEW = 0,
-  GATHERING = 1,
-  COMPLETE = 2
-}
-
-/**
- * ICE candidate types
- */
-export enum IceCandidateType {
-  HOST = 0,
-  SRFLX = 1,
-  PRFLX = 2,
-  RELAY = 3
-}
-
-/**
- * Main RatsClient class for peer-to-peer networking
- */
-export class RatsClient {
-  /**
-   * Create a new RatsClient instance
-   * @param listenPort - Port to listen on for incoming connections
-   */
-  constructor(listenPort: number);
-
-  // ============ Basic Operations ============
-
-  /**
-   * Start the client
-   * @returns true if started successfully, false otherwise
-   */
-  start(): boolean;
-
-  /**
-   * Stop the client
-   */
-  stop(): void;
-
-  /**
-   * Connect to a peer
-   * @param host - IP address or hostname of the peer
-   * @param port - Port number of the peer
-   * @returns true if connection initiated successfully
-   */
-  connect(host: string, port: number): boolean;
-
-  /**
-   * Disconnect from a peer
-   * @param peerId - ID of the peer to disconnect from
-   */
-  disconnect(peerId: string): void;
-
-  // ============ Information ============
-
-  /**
-   * Get the port the client is listening on
-   * @returns Listen port number
-   */
-  getListenPort(): number;
-
-  /**
-   * Get the number of connected peers
-   * @returns Number of connected peers
-   */
-  getPeerCount(): number;
-
-  /**
-   * Get our own peer ID
-   * @returns Our peer ID, or null if not started
-   */
-  getOurPeerId(): string | null;
-
-  /**
-   * Get list of connected peer IDs
-   * @returns Array of peer IDs
-   */
-  getPeerIds(): string[];
-
-  /**
-   * Get connection statistics as JSON string
-   * @returns JSON string with statistics, or null if unavailable
-   */
-  getConnectionStatistics(): string | null;
-
-  /**
-   * Get file transfer statistics as JSON string
-   * @returns JSON string with statistics, or null if unavailable
-   */
-  getFileTransferStatistics(): string | null;
-
-  // ============ Peer Management ============
-
-  /**
-   * Set maximum number of peers
-   * @param maxPeers - Maximum number of peers to allow
-   * @returns true if set successfully
-   */
-  setMaxPeers(maxPeers: number): boolean;
-
-  /**
-   * Get maximum number of peers
-   * @returns Maximum number of peers allowed
-   */
-  getMaxPeers(): number;
-
-  /**
-   * Check if peer limit has been reached
-   * @returns true if at or over peer limit
-   */
-  isPeerLimitReached(): boolean;
-
-  // ============ Messaging ============
-
-  /**
-   * Send a string message to a peer
-   * @param peerId - ID of the peer to send to
-   * @param message - String message to send
-   * @returns true if sent successfully
-   */
-  sendString(peerId: string, message: string): boolean;
-
-  /**
-   * Send binary data to a peer
-   * @param peerId - ID of the peer to send to
-   * @param data - Buffer containing binary data
-   * @returns true if sent successfully
-   */
-  sendBinary(peerId: string, data: Buffer): boolean;
-
-  /**
-   * Send JSON data to a peer
-   * @param peerId - ID of the peer to send to
-   * @param jsonStr - JSON string to send
-   * @returns true if sent successfully
-   */
-  sendJson(peerId: string, jsonStr: string): boolean;
-
-  /**
-   * Broadcast a string message to all connected peers
-   * @param message - String message to broadcast
-   * @returns Number of peers the message was sent to
-   */
-  broadcastString(message: string): number;
-
-  /**
-   * Broadcast binary data to all connected peers
-   * @param data - Buffer containing binary data
-   * @returns Number of peers the data was sent to
-   */
-  broadcastBinary(data: Buffer): number;
-
-  /**
-   * Broadcast JSON data to all connected peers
-   * @param jsonStr - JSON string to broadcast
-   * @returns Number of peers the data was sent to
-   */
-  broadcastJson(jsonStr: string): number;
-
-  // ============ File Transfer ============
-
-  /**
-   * Send a file to a peer
-   * @param peerId - ID of the peer to send to
-   * @param filePath - Local path to the file
-   * @param remoteFilename - Optional filename on remote side
-   * @returns Transfer ID, or null if failed
-   */
-  sendFile(peerId: string, filePath: string, remoteFilename?: string): string | null;
-
-  /**
-   * Send a directory to a peer. Directory transfers are always recursive.
-   * @param peerId - ID of the peer to send to
-   * @param dirPath - Local path to the directory
-   * @param remoteDirName - Optional directory name on remote side
-   * @returns Transfer ID, or null if failed
-   */
-  sendDirectory(peerId: string, dirPath: string, remoteDirName?: string): string | null;
-
-  /**
-   * Accept an incoming file transfer
-   * @param transferId - ID of the transfer to accept
-   * @param localPath - Local path where file should be saved
-   * @returns true if accepted successfully
-   */
-  acceptFileTransfer(transferId: string, localPath: string): boolean;
-
-  /**
-   * Reject an incoming file transfer
-   * @param transferId - ID of the transfer to reject
-   * @param reason - Optional reason for rejection
-   * @returns true if rejected successfully
-   */
-  rejectFileTransfer(transferId: string, reason?: string): boolean;
-
-  /**
-   * Cancel an ongoing file transfer
-   * @param transferId - ID of the transfer to cancel
-   * @returns true if cancelled successfully
-   */
-  cancelFileTransfer(transferId: string): boolean;
-
-  /**
-   * Pause a file transfer
-   * @param transferId - ID of the transfer to pause
-   * @returns true if paused successfully
-   */
-  pauseFileTransfer(transferId: string): boolean;
-
-  /**
-   * Resume a paused file transfer
-   * @param transferId - ID of the transfer to resume
-   * @returns true if resumed successfully
-   */
-  resumeFileTransfer(transferId: string): boolean;
-
-  /**
-   * Get file transfer progress information as JSON string
-   * @param transferId - ID of the transfer to query
-   * @returns JSON string with progress info, or null if not found
-   */
-  getFileTransferProgress(transferId: string): string | null;
-
-  // ============ GossipSub ============
-
-  /**
-   * Check if GossipSub is available
-   * @returns true if GossipSub is available
-   */
-  isGossipsubAvailable(): boolean;
-
-  /**
-   * Check if GossipSub is running
-   * @returns true if GossipSub is running
-   */
-  isGossipsubRunning(): boolean;
-
-  /**
-   * Subscribe to a topic
-   * @param topic - Topic name to subscribe to
-   * @returns true if subscribed successfully
-   */
-  subscribeToTopic(topic: string): boolean;
-
-  /**
-   * Unsubscribe from a topic
-   * @param topic - Topic name to unsubscribe from
-   * @returns true if unsubscribed successfully
-   */
-  unsubscribeFromTopic(topic: string): boolean;
-
-  /**
-   * Check if subscribed to a topic
-   * @param topic - Topic name to check
-   * @returns true if subscribed
-   */
-  isSubscribedToTopic(topic: string): boolean;
-
-  /**
-   * Publish a message to a topic
-   * @param topic - Topic name to publish to
-   * @param message - Message to publish
-   * @returns true if published successfully
-   */
-  publishToTopic(topic: string, message: string): boolean;
-
-  /**
-   * Publish JSON data to a topic
-   * @param topic - Topic name to publish to
-   * @param jsonStr - JSON string to publish
-   * @returns true if published successfully
-   */
-  publishJsonToTopic(topic: string, jsonStr: string): boolean;
-
-  /**
-   * Get list of subscribed topics
-   * @returns Array of topic names
-   */
-  getSubscribedTopics(): string[];
-
-  /**
-   * Get peers subscribed to a topic
-   * @param topic - Topic name
-   * @returns Array of peer IDs
-   */
-  getTopicPeers(topic: string): string[];
-
-  /**
-   * Get GossipSub statistics as JSON string
-   * @returns JSON string with statistics, or null if unavailable
-   */
-  getGossipsubStatistics(): string | null;
-
-  // ============ DHT ============
-
-  /**
-   * Start DHT discovery
-   * @param dhtPort - Port to use for DHT
-   * @returns true if started successfully
-   */
-  startDhtDiscovery(dhtPort: number): boolean;
-
-  /**
-   * Stop DHT discovery
-   */
-  stopDhtDiscovery(): void;
-
-  /**
-   * Check if DHT is running
-   * @returns true if DHT is running
-   */
-  isDhtRunning(): boolean;
-
-  /**
-   * Get DHT routing table size
-   * @returns Number of entries in the routing table
-   */
-  getDhtRoutingTableSize(): number;
-
-  /**
-   * Announce availability for a content hash
-   * @param contentHash - Hash to announce for
-   * @param port - Port to announce
-   * @param callback - Optional callback to receive discovered peers during DHT traversal
-   * @returns true if announced successfully
-   */
-  announceForHash(contentHash: string, port: number, callback?: (peers: string[]) => void): boolean;
-
-  // ============ mDNS ============
-
-  /**
-   * Start mDNS discovery
-   * @param serviceName - Service name to advertise
-   * @returns true if started successfully
-   */
-  startMdnsDiscovery(serviceName: string): boolean;
-
-  /**
-   * Stop mDNS discovery
-   */
-  stopMdnsDiscovery(): void;
-
-  /**
-   * Check if mDNS is running
-   * @returns true if mDNS is running
-   */
-  isMdnsRunning(): boolean;
-
-  /**
-   * Query for mDNS services
-   * @returns true if query sent successfully
-   */
-  queryMdnsServices(): boolean;
-
-  // ============ Address Blocking ============
-
-  /**
-   * Add an IP address to the ignore list
-   * @param ipAddress - IP address to ignore
-   */
-  addIgnoredAddress(ipAddress: string): void;
-
-  // ============ Encryption ============
-
-  /**
-   * Enable or disable encryption
-   * @param enabled - Whether encryption should be enabled
-   * @returns true if set successfully
-   */
-  setEncryptionEnabled(enabled: boolean): boolean;
-
-  /**
-   * Check if encryption is enabled
-   * @returns true if encryption is enabled
-   */
-  isEncryptionEnabled(): boolean;
-
-  /**
-   * Initialize encryption system
-   * @param enable - Whether to enable encryption
-   * @returns true if initialized successfully
-   */
-  initializeEncryption(enable: boolean): boolean;
-
-  /**
-   * Check if a specific peer connection is encrypted
-   * @param peerId - Peer ID to check
-   * @returns true if peer connection is encrypted
-   */
-  isPeerEncrypted(peerId: string): boolean;
-
-  /**
-   * Set custom Noise Protocol static keypair
-   * @param privateKeyHex - 32-byte private key as 64-char hex string
-   * @returns true if set successfully
-   */
-  setNoiseStaticKeypair(privateKeyHex: string): boolean;
-
-  /**
-   * Get our Noise Protocol static public key
-   * @returns 64-char hex string, or null if not available
-   */
-  getNoiseStaticPublicKey(): string | null;
-
-  /**
-   * Get remote peer's Noise static public key
-   * @param peerId - Peer ID to query
-   * @returns 64-char hex string, or null if not available
-   */
-  getPeerNoisePublicKey(peerId: string): string | null;
-
-  /**
-   * Get handshake hash for channel binding
-   * @param peerId - Peer ID to query
-   * @returns 64-char hex string, or null if not available
-   */
-  getPeerHandshakeHash(peerId: string): string | null;
-
-  // ============ ICE (NAT Traversal) ============
-
-  /**
-   * Check if ICE is available
-   * @returns true if ICE is available
-   */
-  isIceAvailable(): boolean;
-
-  /**
-   * Add a STUN server for NAT traversal
-   * @param host - STUN server hostname or IP
-   * @param port - STUN server port (default: 3478)
-   */
-  addStunServer(host: string, port?: number): void;
-
-  /**
-   * Add a TURN server for relay-based NAT traversal
-   * @param host - TURN server hostname or IP
-   * @param port - TURN server port
-   * @param username - TURN username
-   * @param password - TURN password
-   */
-  addTurnServer(host: string, port: number, username: string, password: string): void;
-
-  /**
-   * Clear all ICE (STUN/TURN) servers
-   */
-  clearIceServers(): void;
-
-  /**
-   * Start gathering ICE candidates
-   * @returns true if gathering started successfully
-   */
-  gatherIceCandidates(): boolean;
-
-  /**
-   * Get local ICE candidates as JSON string
-   * @returns JSON string of candidates, or null if unavailable
-   */
-  getIceCandidates(): string | null;
-
-  /**
-   * Check if ICE candidate gathering is complete
-   * @returns true if gathering is complete
-   */
-  isIceGatheringComplete(): boolean;
-
-  /**
-   * Get public address discovered via STUN
-   * @returns Address string (ip:port), or null if not discovered
-   */
-  getPublicAddress(): string | null;
-
-  /**
-   * Perform a simple STUN binding request to discover public address
-   * @param stunServer - STUN server hostname (default: "stun.l.google.com")
-   * @param port - STUN server port (default: 19302)
-   * @param timeoutMs - Timeout in milliseconds (default: 5000)
-   * @returns Address string (ip:port), or null on failure
-   */
-  discoverPublicAddress(stunServer?: string, port?: number, timeoutMs?: number): string | null;
-
-  /**
-   * Add a remote ICE candidate from SDP
-   * @param candidateSdp - SDP candidate string
-   */
-  addRemoteIceCandidate(candidateSdp: string): void;
-
-  /**
-   * Signal end of remote ICE candidates (trickle ICE complete)
-   */
-  endOfRemoteIceCandidates(): void;
-
-  /**
-   * Start ICE connectivity checks
-   */
-  startIceChecks(): void;
-
-  /**
-   * Get current ICE connection state
-   * @returns ICE connection state value
-   */
-  getIceConnectionState(): number;
-
-  /**
-   * Get ICE gathering state
-   * @returns ICE gathering state value
-   */
-  getIceGatheringState(): number;
-
-  /**
-   * Check if ICE is connected
-   * @returns true if ICE connection is established
-   */
-  isIceConnected(): boolean;
-
-  /**
-   * Get the selected ICE candidate pair as JSON string
-   * @returns JSON string of selected pair, or null if unavailable
-   */
-  getIceSelectedPair(): string | null;
-
-  /**
-   * Close ICE manager and release resources
-   */
-  closeIce(): void;
-
-  /**
-   * Restart ICE (re-gather candidates and restart checks)
-   */
-  restartIce(): void;
-
-  // ============ Configuration Persistence ============
-
-  /**
-   * Set data directory for configuration files
-   * @param directory - Path to data directory
-   * @returns true if set successfully
-   */
-  setDataDirectory(directory: string): boolean;
-
-  /**
-   * Get current data directory
-   * @returns Path to data directory, or null if not set
-   */
-  getDataDirectory(): string | null;
-
-  /**
-   * Save current configuration to disk
-   * @returns true if saved successfully
-   */
-  saveConfiguration(): boolean;
-
-  /**
-   * Load configuration from disk
-   * @returns true if loaded successfully
-   */
-  loadConfiguration(): boolean;
-
-  // ============ Event Handlers ============
-
-  /**
-   * Set callback for when a peer connects
-   * @param callback - Function to call with peer ID
-   */
-  onConnection(callback: (peerId: string) => void): void;
-
-  /**
-   * Set callback for string messages
-   * @param callback - Function to call with peer ID and message
-   */
-  onString(callback: (peerId: string, message: string) => void): void;
-
-  /**
-   * Set callback for binary messages
-   * @param callback - Function to call with peer ID and data
-   */
-  onBinary(callback: (peerId: string, data: Buffer) => void): void;
-
-  /**
-   * Set callback for JSON messages
-   * @param callback - Function to call with peer ID and JSON string
-   */
-  onJson(callback: (peerId: string, jsonStr: string) => void): void;
-
-  /**
-   * Set callback for when a peer disconnects
-   * @param callback - Function to call with peer ID
-   */
-  onDisconnect(callback: (peerId: string) => void): void;
-
-  /**
-   * Set callback for file transfer progress updates
-   * @param callback - Function to call with transfer ID, progress percentage, and status
-   */
-  onFileProgress(callback: (transferId: string, progressPercent: number, status: string) => void): void;
-
-  /**
-   * Set callback for incoming file/directory transfer offers. Respond by calling
-   * acceptFileTransfer() or rejectFileTransfer() with the given transfer ID.
-   * @param callback - Function to call with peer ID, transfer ID, and the offered file/directory name
-   */
-  onFileRequest(callback: (peerId: string, transferId: string, filename: string) => void): void;
-}
-
-// ============ Utility Functions ============
-
-/**
- * Get the library version as a string
- * @returns Version string (e.g., "1.0.0.123")
- */
-export function getVersionString(): string;
-
-/**
- * Get the library version components
- * @returns Version information object
- */
-export function getVersion(): VersionInfo;
-
-/**
- * Get git describe string
- * @returns Git describe string
- */
-export function getGitDescribe(): string;
-
-/**
- * Get ABI version number
- * @returns ABI version
- */
-export function getAbi(): number;
-
-// ============ Logging Control Functions ============
-
-/**
- * Enable or disable console logging.
- * When disabled, log messages will not be printed to stdout/stderr.
- * File logging (if enabled) will still work.
- * @param enabled - Whether to enable console logging (default: true)
- */
-export function setConsoleLoggingEnabled(enabled: boolean): void;
-
-/**
- * Check if console logging is currently enabled.
- * @returns true if console logging is enabled
- */
-export function isConsoleLoggingEnabled(): boolean;