Runtime Operations

/**
 * Flow management API
 */
interface FlowsAPI {
    getFlows(opts: RequestOptions): Promise<FlowConfig[]>;
    setFlows(opts: RequestOptions & { flows: FlowConfig[]; deploymentType?: string }): Promise<DeploymentResult>;
    addFlow(opts: RequestOptions & { flow: FlowConfig }): Promise<string>;
    getFlow(opts: RequestOptions & { id: string }): Promise<FlowConfig>;
    updateFlow(opts: RequestOptions & { id: string; flow: FlowConfig }): Promise<string>;
    deleteFlow(opts: RequestOptions & { id: string }): Promise<void>;
    getNodeCredentials(opts: RequestOptions & { type: string; id: string }): Promise<object>;
    getState(opts: RequestOptions): Promise<FlowState>;
    setState(opts: RequestOptions & { state: "start" | "stop" }): Promise<FlowState>;
}

/**
 * Get current flow configuration
 * @param opts - Request options
 * @returns Promise resolving to array of flow configurations
 */
RED.runtime.flows.getFlows(opts: RequestOptions): Promise<FlowConfig[]>;

/**
 * Set complete flow configuration (full deployment)
 * @param opts - Request options with flow data
 * @returns Promise resolving to deployment result
 */
RED.runtime.flows.setFlows(opts: RequestOptions & { flows: FlowConfig[] }): Promise<DeploymentResult>;

/**
 * Add a new flow
 * @param opts - Request options with flow configuration
 * @returns Promise resolving to the new flow ID
 */
RED.runtime.flows.addFlow(opts: RequestOptions & { flow: FlowConfig }): Promise<string>;

/**
 * Get individual flow configuration
 * @param opts - Request options with flow ID
 * @returns Promise resolving to flow configuration
 */
RED.runtime.flows.getFlow(opts: RequestOptions & { id: string }): Promise<FlowConfig>;

/**
 * Update existing flow configuration
 * @param opts - Request options with flow ID and updated configuration
 * @returns Promise resolving to the updated flow ID
 */
RED.runtime.flows.updateFlow(opts: RequestOptions & { id: string; flow: FlowConfig }): Promise<string>;

/**
 * Delete a flow
 * @param opts - Request options with flow ID
 * @returns Promise resolving when flow is deleted
 */
RED.runtime.flows.deleteFlow(opts: RequestOptions & { id: string }): Promise<void>;

/**
 * Get node credentials (safe/filtered version)
 * @param opts - Request options with node type and ID
 * @returns Promise resolving to safe credentials object
 */
RED.runtime.flows.getNodeCredentials(opts: RequestOptions & { type: string; id: string }): Promise<object>;

/**
 * Get current flow runtime state
 * @param opts - Request options
 * @returns Promise resolving to flow state information
 */
RED.runtime.flows.getState(opts: RequestOptions): Promise<FlowState>;

/**
 * Set flow runtime state (start/stop flows)
 * @param opts - Request options with target state
 * @returns Promise resolving to updated flow state
 */
RED.runtime.flows.setState(opts: RequestOptions & { state: "start" | "stop" }): Promise<FlowState>;

const RED = require("node-red");

// Get all flows
const flows = await RED.runtime.flows.getFlows({});
console.log(`Found ${flows.length} flows`);

// Add a new flow
const newFlow = {
    type: "tab",
    label: "My New Flow",
    disabled: false,
    info: ""
};
const flowId = await RED.runtime.flows.addFlow({ flow: newFlow });

// Get specific flow
const specificFlow = await RED.runtime.flows.getFlow({ id: flowId });
console.log(`Flow label: ${specificFlow.label}`);

// Update flow
const updatedFlow = { ...specificFlow, label: "Updated Flow Name" };
await RED.runtime.flows.updateFlow({ id: flowId, flow: updatedFlow });

// Deploy flows with validation
const deployResult = await RED.runtime.flows.setFlows({
    flows: updatedFlows,
    deploymentType: "full"
});

// Flow state management
const currentState = await RED.runtime.flows.getState({});
console.log(`Current flow state: ${currentState.state}`);

// Stop flows
const stoppedState = await RED.runtime.flows.setState({ state: "stop" });
console.log(`Flows stopped: ${stoppedState.state}`);

// Start flows
const startedState = await RED.runtime.flows.setState({ state: "start" });
console.log(`Flows started: ${startedState.state}`);

// Get node credentials (returns safe/filtered credentials)
const credentials = await RED.runtime.flows.getNodeCredentials({ 
    type: "mqtt-broker", 
    id: "broker-node-id" 
});
console.log("Has username:", credentials.has_username);

/**
 * Node management API
 */
interface NodesAPI {
    getNodeList(opts: RequestOptions): Promise<NodeInfo[]>;
    getNodeInfo(opts: RequestOptions & { id: string }): Promise<NodeInfo>;
    getNodeConfig(opts: RequestOptions & { id: string; lang?: string }): Promise<string>;
    getNodeConfigs(opts: RequestOptions & { lang?: string }): Promise<string>;
    getModuleInfo(opts: RequestOptions & { module: string }): Promise<ModuleInfo>;
    addModule(opts: RequestOptions & { module?: string; version?: string; tarball?: TarballInfo; url?: string }): Promise<ModuleInfo>;
    removeModule(opts: RequestOptions & { module: string }): Promise<void>;
    setModuleState(opts: RequestOptions & { module: string; enabled: boolean }): Promise<ModuleInfo>;
    setNodeSetState(opts: RequestOptions & { id: string; enabled: boolean }): Promise<NodeInfo>;
    getModuleCatalogs(opts: RequestOptions & { lang?: string }): Promise<object>;
    getModuleCatalog(opts: RequestOptions & { module: string; lang?: string }): Promise<object>;
    getIconList(opts: RequestOptions): Promise<IconList>;
    getIcon(opts: RequestOptions & { module: string; icon: string }): Promise<Buffer | null>;
    getModuleResource(opts: RequestOptions & { module: string; path: string }): Promise<Buffer | null>;
}

/**
 * Get list of all installed node types
 * @param opts - Request options
 * @returns Promise resolving to array of node information
 */
RED.runtime.nodes.getNodeList(opts: RequestOptions): Promise<NodeInfo[]>;

/**
 * Get all node HTML configurations
 * @param opts - Request options with optional language
 * @returns Promise resolving to combined HTML configuration for all nodes
 */
RED.runtime.nodes.getNodeConfigs(opts: RequestOptions & { lang?: string }): Promise<string>;

/**
 * Get information about a specific module
 * @param opts - Request options with module name
 * @returns Promise resolving to module information
 */
RED.runtime.nodes.getModuleInfo(opts: RequestOptions & { module: string }): Promise<ModuleInfo>;

/**
 * Install a node module from npm, tarball, or URL
 * @param opts - Request options with module details
 * @returns Promise resolving to installation result
 */
RED.runtime.nodes.addModule(opts: RequestOptions & { 
    module?: string; 
    version?: string; 
    tarball?: TarballInfo; 
    url?: string 
}): Promise<ModuleInfo>;

/**
 * Remove/uninstall a node module
 * @param opts - Request options with module name
 * @returns Promise resolving when module is uninstalled
 */
RED.runtime.nodes.removeModule(opts: RequestOptions & { module: string }): Promise<void>;

/**
 * Enable or disable an entire module
 * @param opts - Request options with module name and enabled state
 * @returns Promise resolving to updated module information
 */
RED.runtime.nodes.setModuleState(opts: RequestOptions & { module: string; enabled: boolean }): Promise<ModuleInfo>;

/**
 * Enable or disable a specific node set
 * @param opts - Request options with node set ID and enabled state
 * @returns Promise resolving to updated node information
 */
RED.runtime.nodes.setNodeSetState(opts: RequestOptions & { id: string; enabled: boolean }): Promise<NodeInfo>;

/**
 * Get message catalogs for all modules
 * @param opts - Request options with optional language
 * @returns Promise resolving to message catalogs object
 */
RED.runtime.nodes.getModuleCatalogs(opts: RequestOptions & { lang?: string }): Promise<object>;

/**
 * Get message catalog for a specific module
 * @param opts - Request options with module name and optional language
 * @returns Promise resolving to module's message catalog
 */
RED.runtime.nodes.getModuleCatalog(opts: RequestOptions & { module: string; lang?: string }): Promise<object>;

/**
 * Get list of all available icons from installed modules
 * @param opts - Request options
 * @returns Promise resolving to icon list
 */
RED.runtime.nodes.getIconList(opts: RequestOptions): Promise<IconList>;

/**
 * Get icon file as buffer
 * @param opts - Request options with module and icon name
 * @returns Promise resolving to icon buffer or null if not found
 */
RED.runtime.nodes.getIcon(opts: RequestOptions & { module: string; icon: string }): Promise<Buffer | null>;

/**
 * Get module resource file
 * @param opts - Request options with module name and resource path
 * @returns Promise resolving to resource buffer or null if not found
 */
RED.runtime.nodes.getModuleResource(opts: RequestOptions & { module: string; path: string }): Promise<Buffer | null>;

// List all installed nodes
const nodes = await RED.runtime.nodes.getNodeList({});
nodes.forEach(node => {
    console.log(`${node.name}: ${node.enabled ? 'enabled' : 'disabled'}`);
});

// Install a new node module
try {
    const result = await RED.runtime.nodes.addModule({ 
        module: "node-red-contrib-influxdb" 
    });
    console.log(`Installed module: ${result.name}`);
} catch (err) {
    console.error("Installation failed:", err.message);
}

// Enable/disable a specific node set
await RED.runtime.nodes.setNodeSetState({ id: "inject", enabled: false });
await RED.runtime.nodes.setNodeSetState({ id: "inject", enabled: true });

// Enable/disable an entire module
await RED.runtime.nodes.setModuleState({ 
    module: "node-red-contrib-influxdb", 
    enabled: false 
});

// Get module information
const moduleInfo = await RED.runtime.nodes.getModuleInfo({ 
    module: "node-red-contrib-influxdb" 
});
console.log(`Module version: ${moduleInfo.version}`);

// Get available icons
const iconList = await RED.runtime.nodes.getIconList({});
console.log(`Available icons:`, iconList);

// Get specific icon
const iconBuffer = await RED.runtime.nodes.getIcon({ 
    module: "node-red", 
    icon: "inject.svg" 
});
if (iconBuffer) {
    console.log(`Icon size: ${iconBuffer.length} bytes`);
}

/**
 * Settings management API
 */
interface SettingsAPI {
    getRuntimeSettings(opts: RequestOptions): Promise<RuntimeSettings>;
    getUserSettings(opts: RequestOptions): Promise<UserSettings>;
    updateUserSettings(opts: RequestOptions & { settings: Partial<UserSettings> }): Promise<void>;
}

/**
 * Get runtime settings (read-only)
 * @param opts - Request options
 * @returns Promise resolving to runtime settings
 */
RED.runtime.settings.getRuntimeSettings(opts: RequestOptions): Promise<RuntimeSettings>;

/**
 * Get user settings
 * @param opts - Request options  
 * @returns Promise resolving to user settings
 */
RED.runtime.settings.getUserSettings(opts: RequestOptions): Promise<UserSettings>;

// Get runtime information
const runtimeSettings = await RED.runtime.settings.getRuntimeSettings({});
console.log(`Node-RED version: ${runtimeSettings.version}`);
console.log(`Node.js version: ${runtimeSettings.nodeVersion}`);

// Get user preferences
const userSettings = await RED.runtime.settings.getUserSettings({});
console.log(`Theme: ${userSettings.theme}`);

/**
 * Library management API
 */
interface LibraryAPI {
    getEntries(opts: RequestOptions & { library: string; type: string; path?: string }): Promise<LibraryEntry[]>;
    getEntry(opts: RequestOptions & { library: string; type: string; path: string }): Promise<LibraryEntry>;
    saveEntry(opts: RequestOptions & { library: string; type: string; path: string; meta: object; body: string }): Promise<void>;
}

/**
 * Get library entries
 * @param opts - Request options with library details
 * @returns Promise resolving to array of library entries
 */
RED.runtime.library.getEntries(opts: RequestOptions & { 
    library: string; 
    type: string; 
    path?: string 
}): Promise<LibraryEntry[]>;

/**
 * Context management API
 */
interface ContextAPI {
    getValue(opts: RequestOptions & { scope: string; id: string; store?: string; key: string }): Promise<any>;
    setValue(opts: RequestOptions & { scope: string; id: string; store?: string; key: string; value: any }): Promise<void>;
    getKeys(opts: RequestOptions & { scope: string; id: string; store?: string }): Promise<string[]>;
    delete(opts: RequestOptions & { scope: string; id: string; store?: string; key: string }): Promise<void>;
}

/**
 * Get context value
 * @param opts - Request options with context details
 * @returns Promise resolving to context value
 */
RED.runtime.context.getValue(opts: RequestOptions & { 
    scope: 'node' | 'flow' | 'global'; 
    id: string; 
    store?: string; 
    key: string 
}): Promise<any>;

// Get global context value
const value = await RED.runtime.context.getValue({
    scope: "global",
    id: "global",
    key: "myValue"
});

// Set flow context value
await RED.runtime.context.setValue({
    scope: "flow",
    id: "flow-id",
    key: "counter",
    value: 42
});

// Get all keys in node context
const keys = await RED.runtime.context.getKeys({
    scope: "node",
    id: "node-id"
});

/**
 * Project management API
 */
interface ProjectsAPI {
    listProjects(opts: RequestOptions): Promise<ProjectInfo[]>;
    getProject(opts: RequestOptions & { id: string }): Promise<ProjectInfo>;
    createProject(opts: RequestOptions & { project: ProjectConfig }): Promise<void>;
    setActiveProject(opts: RequestOptions & { id: string }): Promise<void>;
    updateProject(opts: RequestOptions & { id: string; update: Partial<ProjectConfig> }): Promise<void>;
    deleteProject(opts: RequestOptions & { id: string }): Promise<void>;
}

/**
 * Diagnostics API
 */
interface DiagnosticsAPI {
    get(opts: RequestOptions & { scope?: string }): Promise<DiagnosticsReport>;
}

/**
 * Get comprehensive diagnostic report
 * @param opts - Request options with optional scope ("basic" or "admin")
 * @returns Promise resolving to diagnostics information including runtime, system, and module details
 */
RED.runtime.diagnostics.get(opts: RequestOptions & { scope?: string }): Promise<DiagnosticsReport>;

// Get basic diagnostic report
const basicReport = await RED.runtime.diagnostics.get({ scope: "basic" });
console.log(`Node-RED version: ${basicReport.runtime.version}`);
console.log(`Node.js version: ${basicReport.nodejs.version}`);
console.log(`Platform: ${basicReport.os.platform}`);
console.log(`Flow state: ${basicReport.runtime.flows.state}`);

// Get all installed modules
Object.keys(basicReport.runtime.modules).forEach(module => {
    console.log(`${module}: ${basicReport.runtime.modules[module]}`);
});

// Check containerization status
if (basicReport.os.containerised) {
    console.log(`Running in container: ${basicReport.os.containerised}`);
}

interface RequestOptions {
    user?: UserObject;
    req?: http.IncomingMessage;
}

interface FlowConfig {
    id: string;
    type: string;
    name?: string;
    disabled?: boolean;
    info?: string;
    [key: string]: any;
}

interface DeploymentResult {
    revision: string;
}

interface NodeInfo {
    id: string;
    name: string;
    types: string[];
    enabled: boolean;
    local: boolean;
    module?: string;
    version?: string;
}

interface RuntimeSettings {
    version: string;
    nodeVersion: string;
    user?: UserObject;
    context?: {
        default: string;
        stores: string[];
    };
}

interface LibraryEntry {
    name: string;
    type: 'flows' | 'nodes';
    [key: string]: any;
}

interface ProjectInfo {
    name: string;
    active: boolean;
    current?: boolean;
    [key: string]: any;
}

interface DiagnosticsReport {
    report: "diagnostics";
    scope: string;
    time: {
        utc: string;
        local: string;
    };
    intl: {
        locale: string;
        timeZone: string;
    };
    nodejs: {
        version: string;
        arch: string;
        platform: string;
        memoryUsage: {
            rss: number;
            heapTotal: number;
            heapUsed: number;
            external: number;
            arrayBuffers: number;
        };
    };
    os: {
        containerised: boolean | string;
        wsl: boolean;
        totalmem: number;
        freemem: number;
        arch: string;
        loadavg: number[];
        platform: string;
        release: string;
        type: string;
        uptime: number;
        version: string;
    };
    runtime: {
        version: string;
        isStarted: boolean;
        flows: {
            state: string;
            started: boolean;
        };
        modules: { [moduleName: string]: string };
        settings: {
            available: boolean;
            apiMaxLength: string | number;
            disableEditor: boolean;
            contextStorage: { [storeName: string]: { module: string } };
            debugMaxLength: string | number;
            editorTheme: string | object;
            flowFile: string;
            mqttReconnectTime: string | number;
            serialReconnectTime: string | number;
            socketReconnectTime: string | number;
            socketTimeout: string | number;
            tcpMsgQueueSize: string | number;
            inboundWebSocketTimeout: string | number;
            runtimeState: string | object;
            adminAuth: "SET" | "UNSET";
            httpAdminRoot: string;
            httpAdminCors: "SET" | "UNSET";
            httpNodeAuth: "SET" | "UNSET";
            httpNodeRoot: string;
            httpNodeCors: "SET" | "UNSET";
            httpStatic: "SET" | "UNSET";
            httpStaticRoot: string;
            httpStaticCors: "SET" | "UNSET";
            uiHost: "SET" | "UNSET";
            uiPort: "SET" | "UNSET";
            userDir: "SET" | "UNSET";
            nodesDir: "SET" | "UNSET";
        };
    };
}

interface FlowState {
    state: string;
}

interface ModuleInfo {
    name: string;
    version?: string;
    user?: boolean;
    nodes: NodeInfo[];
    [key: string]: any;
}

interface TarballInfo {
    name: string;
    size: number;
    buffer: Buffer;
}

interface IconList {
    [moduleName: string]: string[];
}