@frp-bridge/core 0.0.2 → 0.0.3

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { NodeRegisterPayload, NodeHeartbeatPayload, NodeInfo as NodeInfo$1, NodeListQuery, NodeListResponse, NodeStatistics, TunnelSyncPayload, ProxyConfig, ClientConfig, ServerConfig, RpcRequest } from '@frp-bridge/types';
+import { NodeRegisterPayload, NodeHeartbeatPayload, NodeInfo as NodeInfo$1, NodeListQuery, NodeListResponse, NodeStatistics, TunnelSyncPayload, ProxyConfig, ClientConfig, ServerConfig, RpcRequest as RpcRequest$1 } from '@frp-bridge/types';
 import { EventEmitter } from 'node:events';
 
 type Awaitable<T> = T | Promise<T>;
@@ -165,7 +165,7 @@ declare class ClientNodeCollector {
 
 interface NodeManagerOptions {
     heartbeatTimeout?: number;
-    logger?: any;
+    logger?: Partial<RuntimeLogger>;
 }
 interface NodeStorage {
     save: (node: NodeInfo$1) => Promise<void> | void;
@@ -185,7 +185,7 @@ declare class NodeManager extends EventEmitter {
     private tunnelRegistry;
     private storage?;
     private heartbeatTimeout;
-    private logger?;
+    private readonly log;
     constructor(context: RuntimeContext, options?: NodeManagerOptions, storage?: NodeStorage);
     initialize(): Promise<void>;
     /** Register a new node (called when client connects) */
@@ -261,8 +261,69 @@ declare class FileNodeStorage implements NodeStorage {
     private updateIndex;
 }
 
+/**
+ * 配置合并方法 - core 包内部使用
+ * 将预设配置和用户配置合并成最终的 frp 配置
+ */
+
+/**
+ * 预设配置接口
+ */
+interface PresetConfig {
+    frps?: FrpsPresetConfig;
+    frpc?: FrpcPresetConfig;
+}
+interface FrpsPresetConfig {
+    bindPort?: number;
+    vhostHTTPPort?: number;
+    vhostHTTPSPort?: number;
+    domain?: string;
+    dashboardPort?: number;
+    dashboardUser?: string;
+    dashboardPassword?: string;
+    authToken?: string;
+    subdomainHost?: string;
+}
+interface FrpcPresetConfig {
+    serverAddr?: string;
+    serverPort?: number;
+    authToken?: string;
+    user?: string;
+    heartbeatInterval?: number;
+}
+/**
+ * 默认预设配置
+ */
+declare const DEFAULT_PRESET_CONFIG: PresetConfig;
+/**
+ * 合并预设配置和用户配置，生成最终的 TOML 配置
+ */
+declare function mergeConfigs(presetConfig: PresetConfig, userConfig: string, type: 'frps' | 'frpc'): string;
+/**
+ * 从 tunnels 数组生成并保存 FRP 配置文件
+ */
+declare function saveFrpConfigFile(configPath: string, tunnels: ProxyConfig[], presetConfig: PresetConfig, type: 'frps' | 'frpc'): void;
+/**
+ * 将配置对象转换为 TOML 格式
+ */
+declare function configToToml(config: Record<string, any>): string;
+/**
+ * 验证预设配置
+ */
+declare function validatePresetConfig(config: PresetConfig, type: 'frps' | 'frpc'): {
+    valid: boolean;
+    errors: string[];
+};
+
 /**
  * FRP process management utilities
+ *
+ * This class serves as a facade that delegates to specialized components:
+ * - ProcessController: Process lifecycle management
+ * - ConfigurationStore: Configuration file operations
+ * - TunnelManager: Tunnel/proxy management
+ * - NodeManager: Node information management
+ * - BinaryManager: Binary file management
  */
 
 interface FrpProcessManagerOptions {
@@ -293,16 +354,27 @@ interface NodeInfo {
 }
 /**
  * Manages FRP client/server lifecycle, config, and tunnels
+ *
+ * This class now serves as a facade that delegates to specialized components:
+ * - ProcessController: Process lifecycle management
+ * - ConfigurationStore: Configuration file operations
+ * - TunnelManager: Tunnel/proxy management
+ * - NodeManager: Node information management
+ * - BinaryManager: Binary file management
  */
 declare class FrpProcessManager extends EventEmitter {
     private readonly workDir;
-    private version;
     private readonly mode;
     private readonly specifiedVersion?;
     private readonly logger;
+    private readonly configPath;
+    private readonly processController;
+    private readonly configStore;
+    private readonly binaryManager;
+    private readonly presetConfigManager;
+    private tunnelManager;
+    private nodeManager;
     private process;
-    private configPath;
-    private binaryPath;
     private uptime;
     private isManualStop;
     constructor(options: FrpProcessManagerOptions);
@@ -315,9 +387,9 @@ declare class FrpProcessManager extends EventEmitter {
     /** Check if binary exists */
     hasBinary(): boolean;
     /** Get current configuration */
-    getConfig(): ClientConfig | ServerConfig | null;
+    getConfig(): Promise<ClientConfig | ServerConfig | null>;
     /** Update configuration */
-    updateConfig(config: Partial<ClientConfig | ServerConfig>): void;
+    updateConfig(config: Partial<ClientConfig | ServerConfig>): Promise<void>;
     /** Backup configuration */
     backupConfig(): Promise<string>;
     /** Return the absolute config file path */
@@ -333,25 +405,36 @@ declare class FrpProcessManager extends EventEmitter {
     /** Check if process is running */
     isRunning(): boolean;
     /** Add node (for client mode) */
-    addNode(node: NodeInfo): void;
+    addNode(node: NodeInfo): Promise<void>;
     /** Get node info */
-    getNode(): NodeInfo | null;
+    getNode(): Promise<NodeInfo | null>;
     /** Update node info */
-    updateNode(node: Partial<NodeInfo>): void;
+    updateNode(node: Partial<NodeInfo>): Promise<void>;
     /** Remove node */
-    removeNode(): void;
+    removeNode(): Promise<void>;
     /** Add tunnel (proxy) */
-    addTunnel(proxy: ProxyConfig): void;
-    /** Check if proxy type uses remotePort */
-    private typeUsesRemotePort;
+    addTunnel(proxy: ProxyConfig): Promise<void>;
     /** Get tunnel by name */
-    getTunnel(name: string): ProxyConfig | null;
+    getTunnel(name: string): Promise<ProxyConfig | null>;
     /** Update tunnel */
-    updateTunnel(name: string, proxy: Partial<ProxyConfig>): void;
+    updateTunnel(name: string, proxy: Partial<ProxyConfig>): Promise<void>;
     /** Remove tunnel */
-    removeTunnel(name: string): void;
+    removeTunnel(name: string): Promise<void>;
     /** List all tunnels */
-    listTunnels(): ProxyConfig[];
+    listTunnels(): Promise<ProxyConfig[]>;
+    /**
+     * 生成 FRP 配置文件（合并预设配置和用户 tunnels）
+     * @param force 是否强制重新生成
+     */
+    generateConfig(force?: boolean): Promise<void>;
+    /**
+     * 获取预设配置
+     */
+    getPresetConfig(): PresetConfig;
+    /**
+     * 保存预设配置
+     */
+    savePresetConfig(config: Record<string, any>): void;
     /**
      * Query current process status
      */
@@ -359,60 +442,452 @@ declare class FrpProcessManager extends EventEmitter {
         pid: number | undefined;
         uptime: number;
     };
-    private setupProcessListeners;
+}
+
+/**
+ * RPC 消息类型定义
+ * 提供类型安全的消息结构和类型守卫
+ */
+/**
+ * RPC 消息类型枚举
+ */
+declare enum RpcMessageType {
+    REGISTER = "register",
+    COMMAND = "command",
+    RESPONSE = "response",
+    PING = "ping",
+    PONG = "pong"
+}
+/**
+ * 节点注册消息
+ */
+interface RegisterMessage {
+    type: RpcMessageType.REGISTER;
+    nodeId: string;
+    payload: Record<string, unknown>;
+}
+/**
+ * RPC 请求
+ */
+interface RpcRequest {
+    id: string;
+    method: string;
+    params: Record<string, unknown>;
+    timeout?: number;
+}
+/**
+ * RPC 响应状态
+ */
+type RpcResponseStatus = 'success' | 'error';
+/**
+ * RPC 响应
+ */
+interface RpcResponse {
+    id: string;
+    status: RpcResponseStatus;
+    result?: unknown;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Ping 消息
+ */
+interface PingMessage {
+    type: RpcMessageType.PING;
+    timestamp: number;
+}
+/**
+ * Pong 消息
+ */
+interface PongMessage {
+    type: RpcMessageType.PONG;
+    timestamp: number;
+}
+/**
+ * 所有 RPC 消息类型
+ */
+type RpcMessage = RegisterMessage | RpcRequest | RpcResponse | PingMessage | PongMessage;
+/**
+ * Event-based RPC message type (matching document spec)
+ */
+interface EventRpcMessage {
+    type: 'command' | 'event';
+    action: string;
+    payload: unknown;
+    id?: string;
+    targetNodeId?: string;
+}
+/**
+ * Command message (frps -> frpc)
+ */
+interface CommandRpcMessage extends EventRpcMessage {
+    type: 'command';
+    id: string;
+}
+/**
+ * Event message (frpc -> frps)
+ */
+interface EventRpcMessageEvent extends EventRpcMessage {
+    type: 'event';
+    id?: string;
+}
+/**
+ * Tunnel add payload
+ */
+interface TunnelAddPayload {
+    name: string;
+    type: 'tcp' | 'http' | 'https' | 'stcp' | 'sudp' | 'xtcp';
+    localPort: number;
+    remotePort?: number;
+    customDomains?: string[];
+    subdomain?: string;
+    nodeId?: string;
+    [key: string]: unknown;
+}
+/**
+ * Tunnel delete payload
+ */
+interface TunnelDeletePayload {
+    name: string;
+    nodeId?: string;
+}
+/**
+ * Tunnel response payload
+ */
+interface TunnelResponsePayload {
+    success: boolean;
+    error?: string;
+    tunnel?: TunnelAddPayload;
+}
+/**
+ * Node delete payload
+ */
+interface NodeDeletePayload {
+    name: string;
+}
+/**
+ * Node response payload
+ */
+interface NodeResponsePayload {
+    success: boolean;
+    error?: string;
+    deletedNode?: string;
+}
+/**
+ * All message types including event-based
+ */
+type AllRpcMessage = RpcMessage | EventRpcMessage;
+/**
+ * 类型守卫：检查是否为注册消息
+ */
+declare function isRegisterMessage(msg: unknown): msg is RegisterMessage;
+/**
+ * 类型守卫：检查是否为 RPC 请求
+ */
+declare function isRpcRequest(msg: unknown): msg is RpcRequest;
+/**
+ * 类型守卫：检查是否为 RPC 响应
+ */
+declare function isRpcResponse(msg: unknown): msg is RpcResponse;
+/**
+ * 类型守卫：检查是否为 Ping 消息
+ */
+declare function isPingMessage(msg: unknown): msg is PingMessage;
+/**
+ * 类型守卫：检查是否为 Pong 消息
+ */
+declare function isPongMessage(msg: unknown): msg is PongMessage;
+/**
+ * 类型守卫：检查是否为 Event-based RPC 消息
+ */
+declare function isEventRpcMessage(msg: unknown): msg is EventRpcMessage;
+/**
+ * 类型守卫：检查是否为 Command 消息
+ */
+declare function isCommandMessage(msg: unknown): msg is CommandRpcMessage;
+/**
+ * 类型守卫：检查是否为 Event 消息
+ */
+declare function isEventMessage(msg: unknown): msg is EventRpcMessageEvent;
+/**
+ * 类型守卫：检查是否为 TunnelAddPayload
+ */
+declare function isTunnelAddPayload(data: unknown): data is TunnelAddPayload;
+/**
+ * 类型守卫：检查是否为 TunnelDeletePayload
+ */
+declare function isTunnelDeletePayload(data: unknown): data is TunnelDeletePayload;
+/**
+ * 类型守卫：检查是否为 NodeDeletePayload
+ */
+declare function isNodeDeletePayload(data: unknown): data is NodeDeletePayload;
+
+/**
+ * RPC 中间件系统
+ * 提供可扩展的请求处理管道
+ */
+
+/**
+ * 中间件上下文
+ */
+interface MiddlewareContext {
+    request: RpcRequest;
+    response: Partial<RpcResponse>;
+    startTime: number;
+}
+/**
+ * 中间件函数类型
+ */
+type MiddlewareFn = (context: MiddlewareContext, next: () => Promise<void>) => Promise<void>;
+/**
+ * 中间件选项
+ */
+interface MiddlewareOptions {
+    preHooks?: MiddlewareFn[];
+    postHooks?: MiddlewareFn[];
+}
+/**
+ * 日志中间件
+ */
+declare function loggingMiddleware(logger?: {
+    info?: (msg: string, data?: unknown) => void;
+    warn?: (msg: string, data?: unknown) => void;
+    error?: (msg: string, data?: unknown) => void;
+}): MiddlewareFn;
+/**
+ * 认证中间件
+ */
+declare function authMiddleware(validateToken: (token: string | undefined) => boolean | Promise<boolean>): MiddlewareFn;
+/**
+ * 超时中间件
+ */
+declare function timeoutMiddleware(timeoutMs: number): MiddlewareFn;
+/**
+ * 错误处理中间件
+ */
+declare function errorHandlerMiddleware(logger?: {
+    error?: (msg: string, data?: unknown) => void;
+}): MiddlewareFn;
+/**
+ * 中间件管道
+ */
+declare class MiddlewarePipeline {
+    private middlewares;
+    /**
+     * 添加中间件
+     */
+    use(middleware: MiddlewareFn): this;
+    /**
+     * 执行中间件管道
+     */
+    execute(request: RpcRequest, handler: () => Promise<unknown>): Promise<Partial<RpcResponse>>;
+    /**
+     * 执行处理器
+     */
+    private executeHandler;
+    /**
+     * 清空中间件
+     */
+    clear(): void;
+}
+
+/**
+ * RPC 重连策略
+ * 提供可配置的重连机制，包括指数退避
+ */
+/**
+ * 重连策略接口
+ */
+interface ReconnectStrategy {
+    /**
+     * 判断是否应该重连
+     */
+    shouldReconnect: (attempt: number) => boolean;
+    /**
+     * 获取重连延迟时间（毫秒）
+     */
+    getDelay: (attempt: number) => number;
+    /**
+     * 达到最大重连次数时的回调
+     */
+    onMaxAttemptsReached: () => void;
+}
+/**
+ * 指数退避重连策略
+ */
+declare class ExponentialBackoffStrategy implements ReconnectStrategy {
+    private maxAttempts;
+    private baseDelay;
+    private maxDelay;
+    private logger?;
+    constructor(maxAttempts?: number, baseDelay?: number, maxDelay?: number, logger?: {
+        error?: (msg: string, data?: unknown) => void;
+    } | undefined);
+    shouldReconnect(attempt: number): boolean;
+    getDelay(attempt: number): number;
+    onMaxAttemptsReached(): void;
+}
+/**
+ * 固定间隔重连策略
+ */
+declare class FixedIntervalStrategy implements ReconnectStrategy {
+    private maxAttempts;
+    private interval;
+    private logger?;
+    constructor(maxAttempts?: number, interval?: number, logger?: {
+        error?: (msg: string, data?: unknown) => void;
+    } | undefined);
+    shouldReconnect(attempt: number): boolean;
+    getDelay(): number;
+    onMaxAttemptsReached(): void;
+}
+/**
+ * 线性增长重连策略
+ */
+declare class LinearBackoffStrategy implements ReconnectStrategy {
+    private maxAttempts;
+    private baseDelay;
+    private increment;
+    private maxDelay;
+    private logger?;
+    constructor(maxAttempts?: number, baseDelay?: number, increment?: number, maxDelay?: number, logger?: {
+        error?: (msg: string, data?: unknown) => void;
+    } | undefined);
+    shouldReconnect(attempt: number): boolean;
+    getDelay(attempt: number): number;
+    onMaxAttemptsReached(): void;
+}
+/**
+ * 无限重连策略（永不停止）
+ */
+declare class InfiniteReconnectStrategy implements ReconnectStrategy {
+    private baseDelay;
+    private maxDelay;
+    constructor(baseDelay?: number, maxDelay?: number);
+    shouldReconnect(): boolean;
+    getDelay(attempt: number): number;
+    onMaxAttemptsReached(): void;
 }
 
 interface RpcClientOptions {
     url: string;
     nodeId: string;
     getRegisterPayload: () => Promise<NodeInfo$1> | NodeInfo$1;
-    handleRequest: (req: RpcRequest) => Promise<unknown>;
-    reconnectInterval?: number;
-    logger?: {
-        info?: (msg: string, data?: unknown) => void;
-        warn?: (msg: string, data?: unknown) => void;
-        error?: (msg: string, data?: unknown) => void;
-    };
+    handleRequest: (req: RpcRequest$1) => Promise<unknown>;
+    handleCommand?: (command: CommandRpcMessage) => Promise<unknown>;
+    reconnectStrategy?: ReconnectStrategy;
+    logger?: Partial<RuntimeLogger>;
 }
 declare class RpcClient {
     private readonly options;
     private ws;
     private reconnectTimer?;
-    private readonly reconnectInterval;
+    private reconnectAttempt;
+    private readonly reconnectStrategy;
+    private connectionState;
+    private readonly log;
     constructor(options: RpcClientOptions);
     connect(): Promise<void>;
     disconnect(): void;
+    /**
+     * Get current connection state
+     */
+    getConnectionState(): 'connecting' | 'connected' | 'disconnected';
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Send an event message to server (matching document spec)
+     */
+    sendEvent(event: EventRpcMessageEvent): boolean;
     private createConnection;
     private handleMessage;
+    /**
+     * Handle event-based command messages from server (matching document spec)
+     */
+    private handleCommandEvent;
     private handleRpcRequest;
     private send;
     private scheduleReconnect;
 }
 
+/**
+ * Command status for tracking
+ */
+interface RpcCommandStatus {
+    commandId: string;
+    nodeId: string;
+    action: string;
+    status: 'pending' | 'completed' | 'failed';
+    result?: unknown;
+    error?: string;
+    timestamp: number;
+}
 interface RpcServerOptions {
     port: number;
     heartbeatInterval?: number;
-    logger?: {
-        info?: (msg: string, data?: unknown) => void;
-        warn?: (msg: string, data?: unknown) => void;
-        error?: (msg: string, data?: unknown) => void;
-    };
     validateToken?: (token: string | undefined, nodeId: string | undefined) => boolean | Promise<boolean>;
     authorize?: (nodeId: string, method: string) => boolean | Promise<boolean>;
     onRegister?: (nodeId: string, payload: NodeInfo$1) => void | Promise<void>;
+    onEvent?: (nodeId: string, event: EventRpcMessage) => void | Promise<void>;
+    commandTimeout?: number;
+    logger?: Partial<RuntimeLogger>;
 }
 declare class RpcServer {
     private readonly options;
     private readonly clients;
     private readonly pendingRequests;
+    private readonly commandStatuses;
     private readonly wsToNode;
     private heartbeatTimer?;
     private server?;
+    private readonly defaultCommandTimeout;
+    private readonly log;
     constructor(options: RpcServerOptions);
     start(): void;
     stop(): void;
     rpcCall(nodeId: string, method: string, params: Record<string, unknown>, timeout?: number): Promise<unknown>;
+    /**
+     * Send event-based message to a specific node (matching document spec)
+     */
+    sendToNode(nodeId: string, message: EventRpcMessage): boolean;
+    /**
+     * Broadcast event-based message to all connected nodes
+     */
+    broadcast(message: EventRpcMessage): void;
+    /**
+     * Get list of all online node IDs
+     */
+    getOnlineNodes(): string[];
+    /**
+     * Check if a specific node is online
+     */
+    isNodeOnline(nodeId: string): boolean;
+    /**
+     * Get the count of online nodes
+     */
+    getOnlineNodeCount(): number;
+    /**
+     * Get command status by ID
+     */
+    getRpcCommandStatus(commandId: string): RpcCommandStatus | undefined;
+    /**
+     * Get all command statuses
+     */
+    getAllRpcCommandStatuses(): RpcCommandStatus[];
+    /**
+     * Clear completed/failed command statuses older than specified milliseconds
+     */
+    clearOldStatuses(maxAge?: number): void;
     private handleMessage;
+    /**
+     * Handle event-based messages from clients
+     */
+    private handleEventMessage;
+    private handleRegister;
     private handleRpcResponse;
     private handleClose;
     private startHeartbeat;
@@ -434,12 +909,15 @@ interface FrpBridgeRpcOptions {
     serverHeartbeatInterval?: number;
     serverValidateToken?: (token: string | undefined, nodeId: string | undefined) => boolean | Promise<boolean>;
     serverAuthorize?: (nodeId: string, method: string) => boolean | Promise<boolean>;
+    serverOnRegister?: (nodeId: string, payload: NodeInfo$1) => void | Promise<void>;
+    serverOnEvent?: (nodeId: string, event: EventRpcMessage) => void | Promise<void>;
+    serverCommandTimeout?: number;
     clientUrl?: string;
     clientNodeId?: string;
     clientToken?: string;
     clientReconnectInterval?: number;
     getRegisterPayload?: () => Promise<NodeInfo$1> | NodeInfo$1;
-    handleRequest?: (req: RpcRequest) => Promise<unknown>;
+    handleRequest?: (req: RpcRequest$1) => Promise<unknown>;
 }
 
 interface FrpBridgeOptions {
@@ -531,26 +1009,122 @@ declare const ARCH_MAP: Record<string, string>;
 /** Platform OS mapping */
 declare const OS_MAP: Record<string, string>;
 
-/** Custom error for FRP Bridge operations */
-declare class FrpBridgeError extends Error {
+/**
+ * Base error class for all FRP Bridge errors
+ * Provides consistent error structure and handling
+ */
+declare abstract class FrpBridgeErrorBase extends Error {
+    /**
+     * Error code for programmatic error handling
+     */
+    abstract readonly code: string;
+    /**
+     * HTTP status code (optional, for API responses)
+     */
+    readonly statusCode?: number;
+    /**
+     * Additional error details
+     */
+    readonly details?: unknown;
+    constructor(message: string, details?: unknown);
+    /**
+     * Convert error to plain object for serialization
+     */
+    toJSON(): {
+        code: string;
+        message: string;
+        statusCode?: number;
+        details?: unknown;
+    };
+}
+/**
+ * Generic error for uncategorized errors
+ */
+declare class GenericError extends FrpBridgeErrorBase {
     readonly code: string;
-    readonly details?: unknown | undefined;
-    constructor(message: string, code: string, details?: unknown | undefined);
-}
-/** Error codes */
-declare enum ErrorCode {
-    BINARY_NOT_FOUND = "BINARY_NOT_FOUND",
-    DOWNLOAD_FAILED = "DOWNLOAD_FAILED",
-    EXTRACTION_FAILED = "EXTRACTION_FAILED",
-    CONFIG_NOT_FOUND = "CONFIG_NOT_FOUND",
-    CONFIG_INVALID = "CONFIG_INVALID",
-    PROCESS_ALREADY_RUNNING = "PROCESS_ALREADY_RUNNING",
-    PROCESS_NOT_RUNNING = "PROCESS_NOT_RUNNING",
-    PROCESS_START_FAILED = "PROCESS_START_FAILED",
-    UNSUPPORTED_PLATFORM = "UNSUPPORTED_PLATFORM",
-    VERSION_FETCH_FAILED = "VERSION_FETCH_FAILED",
-    MODE_ERROR = "MODE_ERROR",
-    NOT_FOUND = "NOT_FOUND"
+    constructor(message: string, code: string, details?: unknown);
+}
+
+/**
+ * Categorized error classes for FRP Bridge
+ * Each error extends FrpBridgeErrorBase directly
+ */
+
+/**
+ * Configuration errors (400 Bad Request)
+ */
+declare class ConfigNotFoundError extends FrpBridgeErrorBase {
+    readonly code = "CONFIG_NOT_FOUND";
+    readonly statusCode = 400;
+}
+declare class ConfigInvalidError extends FrpBridgeErrorBase {
+    readonly code = "CONFIG_INVALID";
+    readonly statusCode = 400;
+}
+/**
+ * Process errors
+ */
+declare class ProcessNotRunningError extends FrpBridgeErrorBase {
+    readonly code = "PROCESS_NOT_RUNNING";
+    readonly statusCode = 409;
+}
+declare class ProcessAlreadyRunningError extends FrpBridgeErrorBase {
+    readonly code = "PROCESS_ALREADY_RUNNING";
+    readonly statusCode = 409;
+}
+declare class ProcessStartFailedError extends FrpBridgeErrorBase {
+    readonly code = "PROCESS_START_FAILED";
+    readonly statusCode = 500;
+}
+/**
+ * Binary errors (500 Internal Server Error)
+ */
+declare class BinaryNotFoundError extends FrpBridgeErrorBase {
+    readonly code = "BINARY_NOT_FOUND";
+    readonly statusCode = 500;
+}
+declare class DownloadFailedError extends FrpBridgeErrorBase {
+    readonly code = "DOWNLOAD_FAILED";
+    readonly statusCode = 500;
+}
+declare class ExtractionFailedError extends FrpBridgeErrorBase {
+    readonly code = "EXTRACTION_FAILED";
+    readonly statusCode = 500;
+}
+/**
+ * Network/Version errors (503 Service Unavailable)
+ */
+declare class VersionFetchError extends FrpBridgeErrorBase {
+    readonly code = "VERSION_FETCH_FAILED";
+    readonly statusCode = 503;
+}
+/**
+ * Validation errors (400 Bad Request)
+ */
+declare class ValidationError extends FrpBridgeErrorBase {
+    readonly code = "VALIDATION_ERROR";
+    readonly statusCode = 400;
+}
+/**
+ * Mode/State errors (409 Conflict)
+ */
+declare class ModeError extends FrpBridgeErrorBase {
+    readonly code = "MODE_ERROR";
+    readonly statusCode = 409;
+}
+/**
+ * Resource not found (404 Not Found)
+ */
+declare class NotFoundError extends FrpBridgeErrorBase {
+    readonly code = "NOT_FOUND";
+    readonly statusCode = 404;
+}
+/**
+ * Platform errors (500 Internal Server Error)
+ */
+declare class PlatformError extends FrpBridgeErrorBase {
+    readonly code = "UNSUPPORTED_PLATFORM";
+    readonly statusCode = 500;
 }
 
 declare class FileSnapshotStorage implements SnapshotStorage {
@@ -562,6 +1136,51 @@ declare class FileSnapshotStorage implements SnapshotStorage {
     private buildPath;
 }
 
+/**
+ * Unified TOML parsing and serialization module
+ * Wraps smol-toml with consistent error handling
+ */
+interface ParseOptions {
+    /**
+     * Parse integers as BigInt
+     */
+    integersAsBigInt?: boolean | 'asNeeded';
+}
+interface StringifyOptions {
+    /**
+     * Serialize numbers as floats
+     */
+    numbersAsFloat?: boolean;
+}
+/**
+ * Parse TOML string to JavaScript object
+ * @param content - TOML string content
+ * @param options - Parse options
+ * @returns Parsed JavaScript object
+ * @throws {Error} If TOML is invalid
+ */
+declare function parse<T = Record<string, any>>(content: string, options?: ParseOptions): T;
+/**
+ * Serialize JavaScript object to TOML string
+ * @param obj - JavaScript object to serialize
+ * @param options - Stringify options
+ * @returns TOML string
+ * @throws {Error} If object contains unserializable values
+ */
+declare function stringify(obj: Record<string, any>, options?: StringifyOptions): string;
+/**
+ * Check if a string is valid TOML
+ * @param content - String content to check
+ * @returns true if valid TOML, false otherwise
+ */
+declare function isValidToml(content: string): boolean;
+/**
+ * Parse TOML file content safely (returns null on error)
+ * @param content - TOML string content
+ * @returns Parsed object or null if parsing fails
+ */
+declare function safeParse<T = Record<string, any>>(content: string): T | null;
+
 /**
  * Utility functions
  */
@@ -582,10 +1201,16 @@ declare function executeCommand(command: string): Promise<{
 declare function commandExists(command: string): Promise<boolean>;
 /** Ensure directory exists */
 declare function ensureDir(dirPath: string): void;
-/** Parse TOML-like config to JSON */
+/** Find existing FRP version in work directory */
+declare function findExistingVersion(workDir: string): string | null;
+/**
+ * Parse TOML-like config to JSON
+ */
 declare function parseToml(content: string): Record<string, any>;
-/** Convert JSON to TOML-like config */
+/**
+ * Convert JSON to TOML-like config
+ */
 declare function toToml(obj: Record<string, any>): string;
 
-export { ARCH_MAP, BINARY_NAMES, ClientNodeCollector, ErrorCode, FileNodeStorage, FileSnapshotStorage, FrpBridge, FrpBridgeError, FrpProcessManager, FrpRuntime, GITHUB_OWNER, GITHUB_REPO, NodeManager, OS_MAP, RpcClient, RpcServer, commandExists, downloadFile, ensureDir, executeCommand, getDownloadUrl, getLatestVersion, getPlatform, parseToml, toToml };
-export type { Awaitable, ClientCollectorOptions, CommandHandler, CommandHandlerContext, CommandMetadata, CommandResult, CommandStatus, ConfigSnapshot, FrpBridgeOptions, FrpProcessManagerOptions, NodeEvent, NodeInfo, NodeManagerOptions, NodeStorage, QueryHandler, QueryResult, RpcClientOptions, RpcServerOptions, RuntimeAdapters, RuntimeCommand, RuntimeContext, RuntimeError, RuntimeErrorCode, RuntimeEvent, RuntimeLogger, RuntimeMode, RuntimeQuery, RuntimeState, RuntimeStatus, SnapshotStorage };
+export { ARCH_MAP, BINARY_NAMES, BinaryNotFoundError, ClientNodeCollector, ConfigInvalidError, ConfigNotFoundError, DEFAULT_PRESET_CONFIG, DownloadFailedError, FrpBridgeErrorBase as Error, ExponentialBackoffStrategy, ExtractionFailedError, FileNodeStorage, FileSnapshotStorage, FixedIntervalStrategy, FrpBridge, FrpBridgeErrorBase, FrpProcessManager, FrpRuntime, GITHUB_OWNER, GITHUB_REPO, GenericError, InfiniteReconnectStrategy, LinearBackoffStrategy, MiddlewarePipeline, ModeError, NodeManager, NotFoundError, OS_MAP, PlatformError, ProcessAlreadyRunningError, ProcessNotRunningError, ProcessStartFailedError, RpcClient, RpcMessageType, RpcServer, ValidationError, VersionFetchError, authMiddleware, commandExists, configToToml, downloadFile, ensureDir, errorHandlerMiddleware, executeCommand, findExistingVersion, getDownloadUrl, getLatestVersion, getPlatform, isCommandMessage, isEventMessage, isEventRpcMessage, isNodeDeletePayload, isPingMessage, isPongMessage, isRegisterMessage, isRpcRequest, isRpcResponse, isTunnelAddPayload, isTunnelDeletePayload, isValidToml, loggingMiddleware, mergeConfigs, parse, parseToml, safeParse, saveFrpConfigFile, stringify, timeoutMiddleware, toToml, validatePresetConfig };
+export type { AllRpcMessage, Awaitable, ClientCollectorOptions, CommandHandler, CommandHandlerContext, CommandMetadata, CommandResult, CommandRpcMessage, CommandStatus, ConfigSnapshot, EventRpcMessage, EventRpcMessageEvent, FrpBridgeOptions, FrpProcessManagerOptions, FrpcPresetConfig, FrpsPresetConfig, MiddlewareContext, MiddlewareFn, MiddlewareOptions, NodeDeletePayload, NodeEvent, NodeInfo, NodeManagerOptions, NodeResponsePayload, NodeStorage, ParseOptions, PingMessage, PongMessage, PresetConfig, QueryHandler, QueryResult, ReconnectStrategy, RegisterMessage, RpcClientOptions, RpcCommandStatus, RpcMessage, RpcRequest, RpcResponse, RpcResponseStatus, RpcServerOptions, RuntimeAdapters, RuntimeCommand, RuntimeContext, RuntimeError, RuntimeErrorCode, RuntimeEvent, RuntimeLogger, RuntimeMode, RuntimeQuery, RuntimeState, RuntimeStatus, SnapshotStorage, StringifyOptions, TunnelAddPayload, TunnelDeletePayload, TunnelResponsePayload };