@bonsae/nrg 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonsae/nrg",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "NRG framework — build Node-RED nodes with Vue 3, TypeScript, and JSON Schema",
   "author": "Allan Oricil <allanoricil@duck.com>",
   "license": "MIT",
@@ -98,6 +98,7 @@
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
     "@types/express": "^5.0.1",
+    "@types/jquery": "^4.0.0",
     "@types/mime-types": "^2.1.4",
     "@types/node": "^22.15.18",
     "@typescript-eslint/eslint-plugin": "^8.32.1",

package/src/core/client/globals.d.ts

@@ -1,17 +1,320 @@
 /**
  * Global type declarations for the Node-RED editor environment.
  * These are provided by Node-RED at runtime, not imported.
+ *
+ * Based on: https://github.com/GogoVega/node-red/blob/33d83d016a0c990c/packages/node_modules/%40node-red/editor-client/types/index.d.ts
  */
 
-// jQuery — injected by Node-RED editor
-declare const $: any;
+/// <reference types="jquery" />
+
+// ---------------------------------------------------------------------------
+// jQuery Node-RED widget extensions
+// ---------------------------------------------------------------------------
+
+interface JQuery<TElement = HTMLElement> {
+  // Node-RED TypedInput widget
+  typedInput(options: NodeRED.TypedInputOptions): this;
+  typedInput(action: "value"): string;
+  typedInput(action: "value", value: string): void;
+  typedInput(action: "type"): string;
+  typedInput(action: "type", value: string): void;
+  typedInput(action: "types", value: any[]): void;
+  typedInput(action: "validate"): boolean;
+  typedInput(
+    action: "validate",
+    options: { returnErrorMessage: boolean },
+  ): string | boolean;
+  typedInput(action: "disable", value?: boolean): void;
+  typedInput(action: "enable"): void;
+  typedInput(action: "focus"): void;
+  typedInput(action: "hide"): void;
+  typedInput(action: "show"): void;
+  typedInput(action: "width", value: string | number): void;
+
+  // Node-RED i18n
+  i18n(): this;
+}
+
+// ---------------------------------------------------------------------------
+// Node-RED editor types
+// ---------------------------------------------------------------------------
+
+declare namespace NodeRED {
+  type UID = string;
+
+  // -- Nodes --
+
+  interface BaseNode {
+    id: UID;
+    type: string;
+    changed: boolean;
+    z?: string;
+    _def: any;
+    [key: string]: any;
+  }
+
+  interface Node extends BaseNode {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    name: string;
+    wires: UID[][];
+    inputs: number;
+    outputs: number;
+    g?: string;
+    _: (key: string) => string;
+  }
+
+  interface ConfigNode extends BaseNode {
+    name: string;
+    credentials?: Record<string, any>;
+    users: BaseNode[];
+    _def: {
+      category: "config";
+      [key: string]: any;
+    };
+  }
+
+  interface Link {
+    source: BaseNode;
+    target: BaseNode;
+    sourcePort: number;
+  }
+
+  interface Workspace {
+    id: UID;
+    type: "tab";
+    label: string;
+    disabled: boolean;
+    info: string;
+  }
+
+  // -- Editor --
+
+  interface EditorOptions {
+    id: string;
+    stateId?: string;
+    mode?: string;
+    value?: string;
+    focus?: boolean;
+    globals?: Record<string, boolean>;
+  }
+
+  interface TrayButton {
+    id?: string;
+    class?: string;
+    click?: (event: JQuery.ClickEvent) => void;
+    text?: string;
+  }
+
+  interface TrayOptions {
+    title?: string;
+    buttons?: TrayButton[];
+    focusElement?: boolean;
+    maximized?: boolean;
+    width?: "inherit" | number | string;
+    overlay?: boolean;
+    open?: (tray: JQuery, done?: () => void) => void;
+    close?: () => void;
+    resize?: (options: { width: number; height?: number }) => void;
+    show?: () => void;
+  }
+
+  // -- Popover --
+
+  interface PopoverOptions {
+    target: JQuery;
+    direction?: string;
+    trigger?: "hover" | "click" | "modal";
+    content: string | JQuery | (() => string | JQuery);
+    delay?: { show: number; hide: number };
+    autoClose?: number;
+    width?: number | string;
+    maxWidth?: number | string;
+    tooltip?: boolean;
+    interactive?: boolean;
+    class?: string;
+  }
+
+  interface PopoverInstance {
+    readonly element: JQuery | null;
+    close(instant?: boolean): PopoverInstance;
+    open(instant?: boolean): PopoverInstance;
+    setContent(content: PopoverOptions["content"]): PopoverInstance;
+    move(options: Partial<PopoverOptions>): void;
+  }
+
+  interface TooltipInstance extends PopoverInstance {
+    delete(): void;
+    setAction(action: string): void;
+  }
+
+  // -- Notifications --
+
+  interface NotificationOptions {
+    type?: "warning" | "compact" | "success" | "error";
+    fixed?: boolean;
+    modal?: boolean;
+    timeout?: number;
+    buttons?: Array<{
+      text: string;
+      class?: string;
+      click?: (event: JQuery.ClickEvent) => void;
+    }>;
+    id?: string;
+  }
+
+  interface NotificationElement {
+    update(msg: string | JQuery, options?: NotificationOptions): void;
+    close(): void;
+  }
+
+  // -- TypedInput --
+
+  type DefaultTypedInputType =
+    (typeof import("../constants").TYPED_INPUT_TYPES)[number];
+
+  interface TypedInputTypeDefinition {
+    value: string;
+    label?: string;
+    icon?: string;
+    hasValue?: boolean;
+    multiple?: boolean;
+    options?: string[] | Array<{ value: string; label: string }>;
+    validate?: ((value: string) => boolean) | RegExp;
+    valueLabel?: (container: JQuery, value: string) => void;
+    autoComplete?: (
+      value: string,
+      done: (result?: Array<{ value: string; label: string | JQuery }>) => void,
+    ) => void;
+  }
+
+  interface TypedInputOptions {
+    default?: DefaultTypedInputType | string;
+    types: Array<DefaultTypedInputType | TypedInputTypeDefinition>;
+    typeField?: JQuery.Selector | JQuery;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// RED global object
+// ---------------------------------------------------------------------------
 
-// Node-RED editor API — injected by Node-RED editor
 declare const RED: {
+  /** Internationalization / translation function */
+  _: (key: string, substitutions?: Record<string, string>) => string;
+
+  /** Node management */
   nodes: {
     registerType(type: string, definition: any): void;
-    node(id: string): any;
+    node(id: NodeRED.UID): NodeRED.BaseNode | null;
     dirty(): boolean;
+    dirty(dirty: boolean): void;
+    eachNode(callback: (node: NodeRED.Node) => void | false): void;
+    eachConfig(callback: (node: NodeRED.ConfigNode) => void | false): void;
+    filterNodes(filter: { z?: NodeRED.UID; type?: string }): NodeRED.BaseNode[];
+    filterLinks(filter: {
+      source?: NodeRED.BaseNode;
+      target?: NodeRED.BaseNode;
+    }): NodeRED.Link[];
+    getType(type: string): any;
+    id(): NodeRED.UID;
+    add(node: any): NodeRED.BaseNode;
+    remove(id: NodeRED.UID): {
+      links: NodeRED.Link[];
+      nodes: NodeRED.BaseNode[];
+    };
+  };
+
+  /** Code editor (ACE/Monaco) */
+  editor: {
+    createEditor(options: NodeRED.EditorOptions): any;
+    edit(node: NodeRED.Node, defaultTab?: any): void;
+    editConfig(
+      name: string,
+      type: string,
+      id: string,
+      prefix?: string,
+      editContext?: NodeRED.Node,
+    ): void;
+    prepareConfigNodeSelect(
+      node: NodeRED.BaseNode,
+      property: string,
+      type: string,
+      prefix?: string,
+      filter?: (configNode: NodeRED.ConfigNode) => boolean,
+    ): void;
+    validateNode(node: NodeRED.BaseNode): boolean;
+  };
+
+  /** Side panel tray */
+  tray: {
+    show(options: NodeRED.TrayOptions): void;
+    close(): void;
+  };
+
+  /** Popover / tooltip */
+  popover: {
+    create(options: NodeRED.PopoverOptions): NodeRED.PopoverInstance;
+    tooltip(
+      target: JQuery,
+      text: string,
+      direction?: string,
+    ): NodeRED.TooltipInstance;
+  };
+
+  /** Toast notifications */
+  notify(
+    message: string | JQuery,
+    options?: NodeRED.NotificationOptions,
+  ): NodeRED.NotificationElement;
+
+  /** Event system */
+  events: {
+    on(event: string, listener: (...args: any[]) => void): void;
+    off(event: string, listener: (...args: any[]) => void): void;
+    emit(event: string, ...args: any[]): void;
+  };
+
+  /** Undo/redo */
+  history: {
+    push(event: any): void;
+    pop(): any;
+    peek(): any;
+    list(): any[];
+  };
+
+  /** Keyboard shortcuts */
+  keyboard: {
+    add(scope: string, key: string, callback: () => void): void;
+    remove(key: string): void;
+  };
+
+  /** Runtime communication (WebSocket) */
+  comms: {
+    subscribe(topic: string, callback: (topic: string, msg: any) => void): void;
+    unsubscribe(
+      topic: string,
+      callback: (topic: string, msg: any) => void,
+    ): void;
+  };
+
+  /** Editor settings */
+  settings: {
+    get(key: string): any;
+    set(key: string, value: any): any;
+    remove(key: string): any;
+    [key: string]: any;
   };
+
+  /** Canvas view */
+  view: {
+    focus(): void;
+    selection(): { nodes?: NodeRED.Node[] };
+    redraw(updateActive?: boolean): void;
+  };
+
+  /** Catch-all for untyped properties */
   [key: string]: any;
 };

package/src/core/server/nodes/node.ts

@@ -1,5 +1,5 @@
 import type { Schema } from "../schemas/types";
-import { type RED } from "../../server/types";
+import { type RED, type NodeRedNode } from "../../server/types";
 import type {
   ConfigNodeContext,
   IONodeContext,
@@ -80,7 +80,7 @@ abstract class Node<TConfig = any, TCredentials = any, TSettings = any> {
     RED.log.info("Settings are valid");
   }
   protected readonly RED: RED;
-  protected readonly node: any;
+  protected readonly node: NodeRedNode;
   protected readonly context!: ConfigNodeContext | IONodeContext;
   public readonly config!: NodeConfig<TConfig>;
 
@@ -89,7 +89,7 @@ abstract class Node<TConfig = any, TCredentials = any, TSettings = any> {
 
   constructor(
     RED: RED,
-    node: any,
+    node: NodeRedNode,
     config: NodeConfig<TConfig>,
     credentials: NodeCredentials<TCredentials>,
   ) {

package/src/core/server/types/index.ts

@@ -1,38 +1,204 @@
-import type { TObject } from "@sinclair/typebox";
+import type { EventEmitter } from "events";
+import type { NodeRedRuntimeSettings } from "../../../types";
 
-interface RED {
-  _: (key: string, substitutions?: Record<string, string>) => string;
-  log: {
-    info(msg: any): void;
-    warn(msg: any): void;
-    error(message: string, error: any): void;
-    debug(msg: any): void;
-    trace(msg: any): void;
-  };
-  nodes: {
-    registerType: (type: string, def: any, opts?: any) => void;
-    getNode: <T = any>(id: string) => T | undefined;
-    createNode: (node: any, config: Record<string, any>) => void;
-    getCredentials: (id: string) => Record<string, any> | undefined;
-  };
-  httpAdmin: {
-    get(path: string, handler: (req: any, res: any) => void): void;
-    post(path: string, handler: (req: any, res: any) => void): void;
-    put(path: string, handler: (req: any, res: any) => void): void;
-    delete(path: string, handler: (req: any, res: any) => void): void;
-  };
-  util: {
-    evaluateNodeProperty(
-      value: any,
-      type: string,
-      node: any,
-      msg: Record<string, any> | undefined,
-      callback: (err: Error | null, result: any) => void,
-    ): void;
+// ---------------------------------------------------------------------------
+// RED.log
+// ---------------------------------------------------------------------------
+
+interface NodeRedLog {
+  info(msg: any): void;
+  warn(msg: any): void;
+  error(msg: any, error?: any): void;
+  debug(msg: any): void;
+  trace(msg: any): void;
+  log(msg: { level: number; msg: string }): void;
+  metric(): boolean;
+  audit(msg: Record<string, any>, req?: any): void;
+  addHandler(handler: (msg: any) => void): void;
+  removeHandler(handler: (msg: any) => void): void;
+  FATAL: 10;
+  ERROR: 20;
+  WARN: 30;
+  INFO: 40;
+  DEBUG: 50;
+  TRACE: 60;
+  AUDIT: 98;
+  METRIC: 99;
+}
+
+// ---------------------------------------------------------------------------
+// Node-RED runtime node (the raw node object from RED.nodes.createNode)
+// ---------------------------------------------------------------------------
+
+interface NodeRedNode {
+  id: string;
+  type: string;
+  name?: string;
+  z?: string;
+  x: number;
+  y: number;
+  g?: string;
+  wires: string[][];
+  credentials: any;
+  _node?: any;
+  send(msg: any): void;
+  receive(msg: any): void;
+  status(
+    status: string | { fill?: string; shape?: string; text?: string },
+  ): void;
+  updateWires(wires: string[][]): void;
+  on(event: string, callback: (...args: any[]) => void): void;
+  log(msg: any): void;
+  warn(msg: any): void;
+  error(msg: any, errorMsg?: any): void;
+  context(): NodeRedNodeContext;
+  [key: string]: any;
+}
+
+interface NodeRedNodeContext extends NodeRedContextStore {
+  flow: NodeRedContextStore;
+  global: NodeRedContextStore;
+}
+
+// ---------------------------------------------------------------------------
+// RED.nodes
+// ---------------------------------------------------------------------------
+
+interface NodeRedNodes {
+  registerType(type: string, constructor: any, opts?: any): void;
+  getNode(id: string): (NodeRedNode & { _node?: any }) | undefined;
+  createNode(node: NodeRedNode, config: Record<string, any>): void;
+  getCredentials(id: string): Record<string, any> | undefined;
+  eachNode(callback: (node: any) => void): void;
+  getType(type: string): any;
+  getNodeInfo(type: string): any;
+  getNodeList(filter?: any): any[];
+  getModuleInfo(module: string): any;
+  installModule(module: string, version?: string): Promise<any>;
+  uninstallModule(module: string): Promise<any>;
+  enableNode(id: string): Promise<any>;
+  disableNode(id: string): Promise<any>;
+}
+
+// ---------------------------------------------------------------------------
+// RED.util
+// ---------------------------------------------------------------------------
+
+interface NodeRedUtil {
+  evaluateNodeProperty(
+    value: any,
+    type: string,
+    node: any,
+    msg: Record<string, any> | undefined,
+    callback: (err: Error | null, result: any) => void,
+  ): void;
+  generateId(): string;
+  cloneMessage<T = any>(msg: T): T;
+  ensureString(o: any): string;
+  ensureBuffer(o: any): Buffer;
+  compareObjects(obj1: any, obj2: any): boolean;
+  getMessageProperty(msg: any, expr: string): any;
+  setMessageProperty(
+    msg: any,
+    prop: string,
+    value: any,
+    createMissing?: boolean,
+  ): void;
+  getObjectProperty(obj: any, expr: string): any;
+  setObjectProperty(
+    obj: any,
+    prop: string,
+    value: any,
+    createMissing?: boolean,
+  ): void;
+  normalisePropertyExpression(
+    str: string,
+    msg?: any,
+    toString?: boolean,
+  ): string[];
+  normaliseNodeTypeName(name: string): string;
+  prepareJSONataExpression(value: string, node: any): any;
+  evaluateJSONataExpression(
+    expr: any,
+    msg: any,
+    callback: (err: Error | null, result: any) => void,
+  ): void;
+  parseContextStore(key: string): {
+    store: string | undefined;
+    key: string;
   };
-  settings: Record<string, any>;
+  getSetting(node: any, name: string, flow?: any): any;
+  encodeObject(obj: any): any;
+}
+
+// ---------------------------------------------------------------------------
+// RED.hooks
+// ---------------------------------------------------------------------------
+
+interface NodeRedHooks {
+  add(hookId: string, callback: (event: any) => void | Promise<void>): void;
+  remove(hookId: string): void;
+  trigger(
+    hookId: string,
+    event: any,
+    callback?: (err?: Error) => void,
+  ): void | Promise<void>;
+  has(hookId: string): boolean;
+  clear(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Express-like HTTP app (httpAdmin / httpNode)
+// ---------------------------------------------------------------------------
+
+type NodeRedRequestHandler = (req: any, res: any, next?: () => void) => void;
+
+interface NodeRedExpressApp {
+  get(path: string, ...handlers: NodeRedRequestHandler[]): void;
+  post(path: string, ...handlers: NodeRedRequestHandler[]): void;
+  put(path: string, ...handlers: NodeRedRequestHandler[]): void;
+  delete(path: string, ...handlers: NodeRedRequestHandler[]): void;
+  patch(path: string, ...handlers: NodeRedRequestHandler[]): void;
+  options(path: string, ...handlers: NodeRedRequestHandler[]): void;
+  head(path: string, ...handlers: NodeRedRequestHandler[]): void;
+  use(
+    path: string | NodeRedRequestHandler,
+    ...handlers: NodeRedRequestHandler[]
+  ): void;
+  all(path: string, ...handlers: NodeRedRequestHandler[]): void;
+}
+
+// ---------------------------------------------------------------------------
+// RED (main interface)
+// ---------------------------------------------------------------------------
+
+interface RED {
+  /** Internationalization function */
+  _(key: string, substitutions?: Record<string, string>): string;
+  /** Logging API */
+  log: NodeRedLog;
+  /** Node registry and management */
+  nodes: NodeRedNodes;
+  /** Utility functions */
+  util: NodeRedUtil;
+  /** Hook system for message lifecycle and module events */
+  hooks: NodeRedHooks;
+  /** Runtime event emitter */
+  events: EventEmitter;
+  /** Express app for admin HTTP endpoints */
+  httpAdmin: NodeRedExpressApp;
+  /** Express app for node HTTP endpoints */
+  httpNode: NodeRedExpressApp;
+  /** Runtime settings (user-provided settings plus node-registered settings) */
+  settings: NodeRedRuntimeSettings & Record<string, any>;
+  /** Node-RED version string */
+  version(): string;
 }
 
+// ---------------------------------------------------------------------------
+// Context store (internal)
+// ---------------------------------------------------------------------------
+
 interface NodeRedContextStore {
   get(
     key: string,
@@ -51,23 +217,4 @@ interface NodeRedContextStore {
   ): void;
 }
 
-interface NodeDefinitionApiResponse {
-  type: string;
-  align?: "left" | "right";
-  category?: "config" | string;
-  color?: `#${string}`;
-  icon?: string;
-  labelStyle?: "node_label" | "node_label_italic" | string;
-  paletteLabel?: string;
-  inputs?: number;
-  outputs?: number;
-  inputLabels?: string | string[];
-  outputLabels?: string | string[];
-  configSchema: TObject | null;
-  credentialsSchema: TObject | null;
-  inputSchema?: TObject | null;
-  outputsSchema?: TObject | null;
-  settingsSchema?: TObject | null;
-}
-
-export { RED, NodeDefinitionApiResponse, NodeRedContextStore };
+export { RED, NodeRedNode, NodeRedNodeContext, NodeRedContextStore };

package/src/core/client/api/index.ts

@@ -1,17 +0,0 @@
-import { type NodeDefinitionApiResponse } from "../../server/types";
-
-async function fetchNodeDefinition(
-  type: string,
-): Promise<NodeDefinitionApiResponse> {
-  const response = await fetch(`/nrg/nodes/${type}`);
-
-  if (!response.ok) {
-    throw new Error(
-      `Failed to fetch node definition for "${type}": ${response.status}`,
-    );
-  }
-
-  return response.json() as Promise<NodeDefinitionApiResponse>;
-}
-
-export { fetchNodeDefinition };

package/src/core/client/virtual.d.ts

@@ -1,5 +0,0 @@
-declare module "virtual:nrg/node-definitions" {
-  import type { NodeDefinitionApiResponse } from "../server/types";
-  const definitions: Record<string, NodeDefinitionApiResponse>;
-  export default definitions;
-}