export type ManagementCommand = { command: string, [key: string]: unknown };

export type ManagementEndpoint = {
    // windows named pipe or unix domain socket
    path?: string,
    port?: number,
};

export interface SendCommandOptions {
    /** Timeout in milliseconds (default: 5000) */
    timeout?: number;
}

/**
 * Send a management command to a running gateway server via its control socket.
 *
 * @param server - Management server configuration (path or port)
 * @param command - Command object with command name and optional parameters
 * @param options - Additional options like timeout
 *
 * @example
 * ```ts
 * // On Windows (named pipe)
 * const result = await sendCommand(
 *     { path: '\\\\.\\pipe\\glue42-gateway-xxx' },
 *     { command: 'info' }
 * );
 *
 * // On Unix/Linux/macOS (Unix socket)
 * const result = await sendCommand(
 *     { path: '/tmp/gateway.sock' },
 *     { command: 'shutdown' }
 * );
 *
 * // Using TCP port
 * const result = await sendCommand(
 *     { port: 9999 },
 *     { command: 'info' }
 * );
 * ```
 */
export function sendCommand(
    server: ManagementEndpoint,
    command: ManagementCommand,
    options?: SendCommandOptions
): Promise<unknown>;