nikcli-remote 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,372 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * @nikcli/remote - Type definitions
+ */
+type SessionStatus = 'starting' | 'waiting' | 'connected' | 'stopped' | 'error';
+type TunnelProvider = 'localtunnel' | 'cloudflared' | 'ngrok' | 'none';
+interface DeviceInfo {
+    id: string;
+    userAgent?: string;
+    connectedAt: Date;
+    lastActivity: Date;
+    ip?: string;
+}
+interface RemoteSession {
+    id: string;
+    name: string;
+    qrCode: string;
+    qrUrl: string;
+    localUrl: string;
+    tunnelUrl?: string;
+    status: SessionStatus;
+    connectedDevices: DeviceInfo[];
+    startedAt: Date;
+    lastActivity: Date;
+    error?: string;
+    port: number;
+}
+interface ServerConfig {
+    /** Port to listen on (0 = auto-assign) */
+    port: number;
+    /** Host to bind to */
+    host: string;
+    /** Enable tunnel for public access */
+    enableTunnel: boolean;
+    /** Tunnel provider */
+    tunnelProvider: TunnelProvider;
+    /** Session secret for authentication */
+    sessionSecret?: string;
+    /** Maximum concurrent connections */
+    maxConnections: number;
+    /** Heartbeat interval in ms */
+    heartbeatInterval: number;
+    /** Shell command to spawn */
+    shell: string;
+    /** Initial terminal columns */
+    cols: number;
+    /** Initial terminal rows */
+    rows: number;
+    /** Working directory for shell */
+    cwd?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Enable terminal (PTY) */
+    enableTerminal: boolean;
+    /** Session timeout in ms (0 = no timeout) */
+    sessionTimeout: number;
+}
+interface BroadcastMessage {
+    type: string;
+    payload: unknown;
+    timestamp?: number;
+}
+interface RemoteNotification {
+    type: 'success' | 'error' | 'warning' | 'info';
+    title: string;
+    body: string;
+    data?: unknown;
+}
+interface ClientMessage {
+    type: string;
+    [key: string]: unknown;
+}
+interface ServerMessage {
+    type: string;
+    payload?: unknown;
+    timestamp: number;
+}
+interface TerminalData {
+    data: string;
+}
+interface TerminalResize {
+    cols: number;
+    rows: number;
+}
+interface CommandMessage {
+    command: string;
+    args?: string[];
+}
+interface ClientConnection {
+    id: string;
+    authenticated: boolean;
+    device: DeviceInfo;
+    lastPing: number;
+}
+declare const DEFAULT_CONFIG: ServerConfig;
+declare const MessageTypes: {
+    readonly AUTH_REQUIRED: "auth:required";
+    readonly AUTH: "auth";
+    readonly AUTH_SUCCESS: "auth:success";
+    readonly AUTH_FAILED: "auth:failed";
+    readonly TERMINAL_OUTPUT: "terminal:output";
+    readonly TERMINAL_INPUT: "terminal:input";
+    readonly TERMINAL_RESIZE: "terminal:resize";
+    readonly TERMINAL_EXIT: "terminal:exit";
+    readonly TERMINAL_CLEAR: "terminal:clear";
+    readonly NOTIFICATION: "notification";
+    readonly PING: "ping";
+    readonly PONG: "pong";
+    readonly SESSION_INFO: "session:info";
+    readonly SESSION_END: "session:end";
+    readonly COMMAND: "command";
+    readonly COMMAND_RESULT: "command:result";
+    readonly AGENT_START: "agent:start";
+    readonly AGENT_PROGRESS: "agent:progress";
+    readonly AGENT_COMPLETE: "agent:complete";
+    readonly AGENT_ERROR: "agent:error";
+};
+
+/**
+ * @nikcli/remote - Native Remote Server
+ * WebSocket-based remote terminal with mobile-friendly web client
+ */
+
+interface RemoteServerEvents {
+    started: (session: RemoteSession) => void;
+    stopped: () => void;
+    'client:connected': (device: DeviceInfo) => void;
+    'client:disconnected': (device: DeviceInfo) => void;
+    'client:error': (clientId: string, error: Error) => void;
+    'tunnel:connected': (url: string) => void;
+    'tunnel:error': (error: Error) => void;
+    command: (cmd: {
+        clientId: string;
+        command: string;
+        args?: string[];
+    }) => void;
+    message: (client: ClientConnection, message: ClientMessage) => void;
+    error: (error: Error) => void;
+}
+declare class RemoteServer extends EventEmitter {
+    private config;
+    private httpServer;
+    private wss;
+    private clients;
+    private session;
+    private terminal;
+    private tunnel;
+    private heartbeatTimer;
+    private sessionTimeoutTimer;
+    private isRunning;
+    private sessionSecret;
+    constructor(config?: Partial<ServerConfig>);
+    /**
+     * Start the remote server
+     */
+    start(options?: {
+        name?: string;
+    }): Promise<RemoteSession>;
+    /**
+     * Stop the server
+     */
+    stop(): Promise<void>;
+    /**
+     * Broadcast message to all authenticated clients
+     */
+    broadcast(message: BroadcastMessage): void;
+    /**
+     * Send notification to clients
+     */
+    notify(notification: RemoteNotification): void;
+    /**
+     * Get current session
+     */
+    getSession(): RemoteSession | null;
+    /**
+     * Check if server is running
+     */
+    isActive(): boolean;
+    /**
+     * Get connected client count
+     */
+    getConnectedCount(): number;
+    /**
+     * Write to terminal
+     */
+    writeToTerminal(data: string): void;
+    /**
+     * Resize terminal
+     */
+    resizeTerminal(cols: number, rows: number): void;
+    /**
+     * Setup WebSocket handlers
+     */
+    private setupWebSocketHandlers;
+    /**
+     * Handle client message
+     */
+    private handleClientMessage;
+    /**
+     * Handle authentication
+     */
+    private handleAuth;
+    /**
+     * Handle HTTP request
+     */
+    private handleHttpRequest;
+    /**
+     * Start heartbeat
+     */
+    private startHeartbeat;
+    /**
+     * Start session timeout
+     */
+    private startSessionTimeout;
+    /**
+     * Reset session timeout
+     */
+    private resetSessionTimeout;
+    /**
+     * Get local IP
+     */
+    private getLocalIP;
+    /**
+     * Generate session ID
+     */
+    private generateSessionId;
+    /**
+     * Generate client ID
+     */
+    private generateClientId;
+    /**
+     * Generate secret
+     */
+    private generateSecret;
+}
+
+/**
+ * @nikcli/remote - Terminal Manager
+ * PTY-based terminal with fallback to basic spawn
+ */
+
+interface TerminalConfig {
+    shell: string;
+    cols: number;
+    rows: number;
+    cwd?: string;
+    env?: Record<string, string>;
+}
+declare class TerminalManager extends EventEmitter {
+    private config;
+    private ptyProcess;
+    private process;
+    private running;
+    constructor(config: TerminalConfig);
+    /**
+     * Start the terminal
+     */
+    start(): void;
+    /**
+     * Write data to terminal
+     */
+    write(data: string): void;
+    /**
+     * Resize terminal
+     */
+    resize(cols: number, rows: number): void;
+    /**
+     * Clear terminal
+     */
+    clear(): void;
+    /**
+     * Kill terminal process
+     */
+    destroy(): void;
+    /**
+     * Check if terminal is running
+     */
+    isRunning(): boolean;
+    /**
+     * Check if using PTY
+     */
+    hasPty(): boolean;
+}
+
+/**
+ * @nikcli/remote - Tunnel Manager
+ * Provides public URL access via various tunnel providers
+ */
+
+declare class TunnelManager {
+    private provider;
+    private process;
+    private url;
+    private tunnelInstance;
+    constructor(provider: TunnelProvider);
+    /**
+     * Create tunnel and return public URL
+     */
+    create(port: number): Promise<string>;
+    /**
+     * Close tunnel
+     */
+    close(): Promise<void>;
+    /**
+     * Get tunnel URL
+     */
+    getUrl(): string | null;
+    /**
+     * Create localtunnel
+     */
+    private createLocaltunnel;
+    /**
+     * Create localtunnel via CLI
+     */
+    private createLocaltunnelCli;
+    /**
+     * Create cloudflared tunnel
+     */
+    private createCloudflared;
+    /**
+     * Create ngrok tunnel
+     */
+    private createNgrok;
+}
+/**
+ * Check if a tunnel provider is available
+ */
+declare function checkTunnelAvailability(provider: TunnelProvider): Promise<boolean>;
+/**
+ * Find best available tunnel provider
+ */
+declare function findAvailableTunnel(): Promise<TunnelProvider | null>;
+
+/**
+ * @nikcli/remote - QR Code Generator
+ * Terminal QR code rendering for session URLs
+ */
+
+interface QROptions {
+    small?: boolean;
+    margin?: number;
+}
+/**
+ * Generate QR code string for terminal display
+ */
+declare function generateQR(url: string, options?: QROptions): Promise<string>;
+/**
+ * Generate QR code as data URL (for web/image)
+ */
+declare function generateQRDataURL(url: string): Promise<string | null>;
+/**
+ * Render session info with QR code
+ */
+declare function renderSessionCard(session: RemoteSession): Promise<string>;
+/**
+ * Simple progress bar
+ */
+declare function progressBar(current: number, total: number, width?: number): string;
+
+/**
+ * @nikcli/remote - Mobile Web Client
+ * Touch-friendly terminal interface for mobile devices
+ */
+declare function getWebClient(): string;
+
+declare function createRemoteServer(config?: Partial<ServerConfig>): Promise<{
+    server: RemoteServer;
+    session: RemoteSession;
+}>;
+
+export { type BroadcastMessage, type ClientConnection, type ClientMessage, type CommandMessage, DEFAULT_CONFIG, type DeviceInfo, MessageTypes, type RemoteNotification, RemoteServer, type RemoteServerEvents, type RemoteSession, type ServerConfig, type ServerMessage, type SessionStatus, type TerminalConfig, type TerminalData, TerminalManager, type TerminalResize, TunnelManager, type TunnelProvider, checkTunnelAvailability, createRemoteServer, findAvailableTunnel, generateQR, generateQRDataURL, getWebClient, progressBar, renderSessionCard };