node-red 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2a448f70ca26bba12cb8a9d4f6a25f93b2956e3144c70f2b215a5b0d1efa320f
+  data.tar.gz: abd51032ec4f34f15f1ef1e5b00dea2c71a7bc4135b519f1838145bb00be42cb
+SHA512:
+  metadata.gz: 1421fecb786a1a74a5db7f094717a28070468a904ad8b67f43c97250c928424a831d76a30fb340f11c369dabb631f55cc0f129edaf9d9cd62604337bbb6ec92b
+  data.tar.gz: 9dcd66078d904b340be8f97faae4730112fc8f41eecf5b975e74efffd1af96033a79bc1efce9be944519724c144841d02308403d9561b198971ed27050d55bac

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+## [0.1.0] - 2025-10-28
+
+- Initial release
+- Full implementation of Node-RED Admin HTTP API wrapper
+- Authentication endpoints (login, token exchange, revoke)
+- Settings and diagnostics endpoints
+- Complete flow management (CRUD operations, state management)
+- Complete node management (install, update, delete modules and sets)
+- Custom error classes for better error handling
+- Comprehensive documentation and examples

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Davide Santangelo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,159 @@
+# Node::Red
+
+A Ruby client library for the Node-RED Admin HTTP API. This gem provides a comprehensive wrapper around the Node-RED Admin API, allowing you to programmatically manage flows, nodes, settings, and authentication.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add node-red
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install node-red
+```
+
+## Usage
+
+### Basic Setup
+
+```ruby
+require 'node/red'
+
+# Create a client instance
+client = Node::Red::Client.new('http://localhost:1880')
+
+# Or with authentication
+client = Node::Red::Client.new('http://localhost:1880', access_token: 'your-access-token')
+```
+
+### Authentication
+
+```ruby
+# Get authentication scheme
+auth_info = client.auth_login
+
+# Exchange credentials for access token
+token_response = client.auth_token(
+  client_id: 'node-red-admin',
+  grant_type: 'password',
+  scope: '*',
+  username: 'admin',
+  password: 'password'
+)
+
+# The access token is automatically set on the client
+puts client.access_token
+
+# Revoke a token
+client.auth_revoke(token_response['access_token'])
+```
+
+### Settings & Diagnostics
+
+```ruby
+# Get runtime settings
+settings = client.settings
+puts settings['httpNodeRoot']
+
+# Get runtime diagnostics
+diagnostics = client.diagnostics
+```
+
+### Flow Management
+
+```ruby
+# Get all flows
+flows = client.flows
+
+# Deploy new flows
+new_flows = [
+  { id: 'tab1', type: 'tab', label: 'Flow 1' },
+  { id: 'node1', type: 'inject', z: 'tab1', name: 'test' }
+]
+response = client.deploy_flows(new_flows)
+
+# Get flow runtime state
+state = client.flows_state
+
+# Set flow runtime state
+client.set_flows_state('stop')  # or 'start'
+
+# Add a single flow
+new_flow = { label: 'New Flow', type: 'tab' }
+created_flow = client.add_flow(new_flow)
+
+# Get a specific flow
+flow = client.flow('flow-id')
+
+# Update a flow
+updated_flow = client.update_flow('flow-id', { label: 'Updated Flow', type: 'tab' })
+
+# Delete a flow
+client.delete_flow('flow-id')
+```
+
+### Node Management
+
+```ruby
+# Get all installed nodes
+nodes = client.nodes
+
+# Install a new node module
+client.install_node('node-red-contrib-example')
+
+# Get node module information
+module_info = client.node_module('node-red-contrib-example')
+
+# Enable/disable a node module
+client.update_node_module('node-red-contrib-example', enabled: false)
+client.update_node_module('node-red-contrib-example', enabled: true)
+
+# Remove a node module
+client.delete_node_module('node-red-contrib-example')
+
+# Get node set information
+set_info = client.node_set('node-red', 'core')
+
+# Enable/disable a node set
+client.update_node_set('node-red', 'core', enabled: true)
+```
+
+### Error Handling
+
+The library provides specific error classes for different error scenarios:
+
+```ruby
+begin
+  client.flow('non-existent-id')
+rescue Node::Red::NotFoundError => e
+  puts "Flow not found: #{e.message}"
+rescue Node::Red::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+rescue Node::Red::ServerError => e
+  puts "Server error: #{e.message}"
+rescue Node::Red::ApiError => e
+  puts "API error: #{e.message}"
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/davidesantangelo/node-red. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/davidesantangelo/node-red/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Node::Red project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/davidesantangelo/node-red/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/examples/basic_usage.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# Example usage of the Node-RED Admin API Ruby client
+#
+# Make sure you have a Node-RED instance running at http://localhost:1880
+# before running this example.
+
+require "node/red"
+
+# Initialize the client
+client = Node::Red::Client.new("http://localhost:1880")
+
+begin
+  # Example 1: Get runtime settings
+  puts "=== Runtime Settings ==="
+  settings = client.settings
+  puts "HTTP Node Root: #{settings["httpNodeRoot"]}"
+  puts "Version: #{settings["version"]}"
+  puts
+
+  # Example 2: Get all flows
+  puts "=== Current Flows ==="
+  flows = client.flows
+  puts "Total flows: #{flows.length}"
+  flows.each do |flow|
+    puts "  - Flow: #{flow["label"]} (#{flow["id"]})" if flow["type"] == "tab"
+  end
+  puts
+
+  # Example 3: Get all installed nodes
+  puts "=== Installed Nodes ==="
+  nodes = client.nodes
+  puts "Total node modules: #{nodes.length}"
+  nodes.take(5).each do |node|
+    puts "  - #{node["id"]} (v#{node["version"]})"
+  end
+  puts
+
+  # Example 4: Get flow runtime state
+  puts "=== Flow Runtime State ==="
+  state = client.flows_state
+  puts "State: #{state["state"]}"
+  puts
+
+  # Example 5: Get diagnostics (if available)
+  puts "=== Diagnostics ==="
+  begin
+    diagnostics = client.diagnostics
+    puts "Node.js version: #{diagnostics["nodejs"]}"
+    puts "OS: #{diagnostics["os"]}"
+  rescue Node::Red::NotFoundError
+    puts "Diagnostics endpoint not available (requires Node-RED 1.1.0+)"
+  end
+  puts
+
+  # Example with authentication (uncomment to use)
+  # puts "=== Authentication Example ==="
+  # token_response = client.auth_token(
+  #   client_id: "node-red-admin",
+  #   grant_type: "password",
+  #   scope: "*",
+  #   username: "admin",
+  #   password: "password"
+  # )
+  # puts "Access token obtained: #{token_response['access_token'][0..20]}..."
+rescue Node::Red::AuthenticationError => e
+  puts "Authentication required: #{e.message}"
+rescue Node::Red::NotFoundError => e
+  puts "Resource not found: #{e.message}"
+rescue Node::Red::ServerError => e
+  puts "Server error: #{e.message}"
+rescue Node::Red::ApiError => e
+  puts "API error: #{e.message}"
+rescue Errno::ECONNREFUSED
+  puts "Error: Could not connect to Node-RED at http://localhost:1880"
+  puts "Make sure Node-RED is running before executing this example."
+end

data/examples/flow_management.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+# Example: Managing flows with Node-RED Admin API
+#
+# This example demonstrates creating, updating, and deleting flows
+
+require "node/red"
+
+# Initialize the client
+client = Node::Red::Client.new("http://localhost:1880")
+
+begin
+  # Get current flows
+  puts "=== Getting Current Flows ==="
+  current_flows = client.flows
+  puts "Current number of flows: #{current_flows.length}"
+  puts
+
+  # Add a new flow
+  puts "=== Adding a New Flow ==="
+  new_flow = {
+    label: "Example Flow",
+    type: "tab",
+    disabled: false,
+    info: "This is an example flow created via the API"
+  }
+
+  created_flow = client.add_flow(new_flow)
+  flow_id = created_flow["id"]
+  puts "Created flow with ID: #{flow_id}"
+  puts "Flow label: #{created_flow["label"]}"
+  puts
+
+  # Get the specific flow
+  puts "=== Getting Specific Flow ==="
+  flow_details = client.flow(flow_id)
+  puts "Flow: #{flow_details["label"]}"
+  puts "Type: #{flow_details["type"]}"
+  puts
+
+  # Update the flow
+  puts "=== Updating Flow ==="
+  updated_flow = {
+    id: flow_id,
+    label: "Updated Example Flow",
+    type: "tab",
+    disabled: false,
+    info: "This flow has been updated"
+  }
+
+  result = client.update_flow(flow_id, updated_flow)
+  puts "Flow updated: #{result["label"]}"
+  puts
+
+  # Example: Deploy flows with nodes
+  puts "=== Deploying Complete Flow Configuration ==="
+
+  # Create a simple flow with an inject and debug node
+  complete_flows = [
+    {
+      id: "flow1",
+      type: "tab",
+      label: "Test Flow"
+    },
+    {
+      id: "inject1",
+      type: "inject",
+      z: "flow1",
+      name: "Test Inject",
+      props: [{ p: "payload" }],
+      repeat: "",
+      crontab: "",
+      once: false,
+      onceDelay: 0.1,
+      topic: "",
+      payload: "Hello from Ruby!",
+      payloadType: "str",
+      x: 150,
+      y: 100
+    },
+    {
+      id: "debug1",
+      type: "debug",
+      z: "flow1",
+      name: "Test Debug",
+      active: true,
+      tosidebar: true,
+      console: false,
+      tostatus: false,
+      complete: "payload",
+      targetType: "msg",
+      x: 350,
+      y: 100,
+      wires: []
+    }
+  ]
+
+  # NOTE: Be careful with deploy_flows as it replaces ALL flows
+  # Uncomment the following lines to deploy
+  # deployment = client.deploy_flows(complete_flows)
+  # puts "Flows deployed with revision: #{deployment['rev']}"
+  puts "Flow deployment commented out for safety"
+  puts
+
+  # Check flow state
+  puts "=== Flow Runtime State ==="
+  state = client.flows_state
+  puts "Current state: #{state["state"]}"
+  puts
+
+  # Stop flows (uncomment to use)
+  # puts "=== Stopping Flows ==="
+  # client.set_flows_state('stop')
+  # puts "Flows stopped"
+  #
+  # sleep 2
+  #
+  # puts "=== Starting Flows ==="
+  # client.set_flows_state('start')
+  # puts "Flows started"
+  # puts
+
+  # Clean up - delete the flow we created
+  puts "=== Deleting Flow ==="
+  client.delete_flow(flow_id)
+  puts "Flow #{flow_id} deleted"
+  puts
+
+  puts "Example completed successfully!"
+rescue Node::Red::NotFoundError => e
+  puts "Error: #{e.message}"
+rescue Node::Red::ApiError => e
+  puts "API Error: #{e.message}"
+rescue Errno::ECONNREFUSED
+  puts "Error: Could not connect to Node-RED at http://localhost:1880"
+  puts "Make sure Node-RED is running before executing this example."
+end

data/examples/node_management.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# Example: Managing nodes with Node-RED Admin API
+#
+# This example demonstrates installing, updating, and removing node modules
+
+require "node/red"
+
+# Initialize the client
+client = Node::Red::Client.new("http://localhost:1880")
+
+begin
+  # List all installed nodes
+  puts "=== Installed Node Modules ==="
+  nodes = client.nodes
+
+  # Group by module
+  modules = nodes.group_by { |n| n["module"] }.keys.compact
+  puts "Total modules installed: #{modules.length}"
+  puts
+
+  # Show first 10 modules
+  puts "Sample of installed modules:"
+  modules.take(10).each do |module_name|
+    puts "  - #{module_name}"
+  end
+  puts
+
+  # Get information about a specific module
+  puts "=== Node-RED Core Module Info ==="
+  begin
+    core_module = client.node_module("node-red")
+    puts "Module: #{core_module["name"]}"
+    puts "Version: #{core_module["version"]}"
+    puts "Nodes in module: #{core_module["nodes"]&.length || 0}"
+  rescue Node::Red::NotFoundError
+    puts "Core module information not available"
+  end
+  puts
+
+  # Install a node module (commented out for safety)
+  puts "=== Installing a Node Module ==="
+  puts "Example (commented out for safety):"
+  puts "  client.install_node('node-red-contrib-example')"
+  puts
+  # Uncomment to actually install:
+  # begin
+  #   result = client.install_node('node-red-contrib-example')
+  #   puts "Module installed: #{result['name']}"
+  # rescue Node::Red::ApiError => e
+  #   puts "Installation failed: #{e.message}"
+  # end
+
+  # Get node set information
+  puts "=== Node Set Information ==="
+  begin
+    # Example: Get info about the inject node set
+    node_set = client.node_set("node-red", "common")
+    puts "Node set: #{node_set["id"]}"
+    puts "Enabled: #{node_set["enabled"]}"
+    puts "Types: #{node_set["types"]&.join(", ")}"
+  rescue Node::Red::NotFoundError
+    puts "Node set not found"
+  end
+  puts
+
+  # Enable/Disable a node module (commented out for safety)
+  puts "=== Enable/Disable Node Module ==="
+  puts "Example (commented out for safety):"
+  puts "  # Disable a module"
+  puts "  client.update_node_module('node-red-contrib-example', enabled: false)"
+  puts
+  puts "  # Enable a module"
+  puts "  client.update_node_module('node-red-contrib-example', enabled: true)"
+  puts
+
+  # Enable/Disable a node set (commented out for safety)
+  puts "=== Enable/Disable Node Set ==="
+  puts "Example (commented out for safety):"
+  puts "  # Disable a node set"
+  puts "  client.update_node_set('node-red', 'common', enabled: false)"
+  puts
+  puts "  # Enable a node set"
+  puts "  client.update_node_set('node-red', 'common', enabled: true)"
+  puts
+
+  # Remove a node module (commented out for safety)
+  puts "=== Removing a Node Module ==="
+  puts "Example (commented out for safety):"
+  puts "  client.delete_node_module('node-red-contrib-example')"
+  puts
+
+  puts "Example completed successfully!"
+  puts
+  puts "Note: Dangerous operations (install/delete/enable/disable) are commented out"
+  puts "for safety. Uncomment them in the source code to test these features."
+rescue Node::Red::AuthenticationError => e
+  puts "Authentication required: #{e.message}"
+rescue Node::Red::ApiError => e
+  puts "API Error: #{e.message}"
+rescue Errno::ECONNREFUSED
+  puts "Error: Could not connect to Node-RED at http://localhost:1880"
+  puts "Make sure Node-RED is running before executing this example."
+end

data/lib/node/red/client.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Node
+  module Red
+    class Client
+      attr_reader :base_url, :access_token
+
+      # Initialize a new Node-RED Admin API client
+      #
+      # @param base_url [String] The base URL of the Node-RED instance (e.g., "http://localhost:1880")
+      # @param access_token [String, nil] Optional access token for authentication
+      def initialize(base_url, access_token: nil)
+        @base_url = base_url.chomp("/")
+        @access_token = access_token
+      end
+
+      # ==================== Authentication Methods ====================
+
+      # Get the active authentication scheme
+      #
+      # @return [Hash] Authentication scheme information
+      def auth_login
+        get("/auth/login")
+      end
+
+      # Exchange credentials for access token
+      #
+      # @param client_id [String] The client ID
+      # @param grant_type [String] The grant type (e.g., "password")
+      # @param scope [String] The scope (e.g., "*" for full access)
+      # @param username [String] The username
+      # @param password [String] The password
+      # @return [Hash] Token response with access_token
+      def auth_token(client_id:, grant_type:, scope:, username:, password:)
+        body = {
+          client_id: client_id,
+          grant_type: grant_type,
+          scope: scope,
+          username: username,
+          password: password
+        }
+        response = post("/auth/token", body, use_auth: false)
+        @access_token = response["access_token"] if response["access_token"]
+        response
+      end
+
+      # Revoke an access token
+      #
+      # @param token [String] The token to revoke
+      # @return [Hash] Revocation response
+      def auth_revoke(token)
+        body = { token: token }
+        post("/auth/revoke", body)
+      end
+
+      # ==================== Settings & Diagnostics ====================
+
+      # Get the runtime settings
+      #
+      # @return [Hash] Runtime settings
+      def settings
+        get("/settings")
+      end
+
+      # Get the runtime diagnostics
+      #
+      # @return [Hash] Runtime diagnostics
+      def diagnostics
+        get("/diagnostics")
+      end
+
+      # ==================== Flow Management ====================
+
+      # Get the active flow configuration
+      #
+      # @return [Array<Hash>] Array of flow configurations
+      def flows
+        get("/flows")
+      end
+
+      # Get the active flow's runtime state
+      #
+      # @return [Hash] Flow runtime state
+      def flows_state
+        get("/flows/state")
+      end
+
+      # Set the active flow configuration
+      #
+      # @param flows [Array<Hash>] The flow configuration
+      # @param rev [String, nil] Optional revision identifier
+      # @return [Hash] Response with revision ID
+      def deploy_flows(flows, rev: nil)
+        body = { flows: flows }
+        body[:rev] = rev if rev
+        post("/flows", body)
+      end
+
+      # Set the active flow's runtime state
+      #
+      # @param state [String] The desired state ("start" or "stop")
+      # @return [Hash] State change response
+      def set_flows_state(state)
+        body = { state: state }
+        post("/flows/state", body)
+      end
+
+      # Add a flow to the active configuration
+      #
+      # @param flow [Hash] The flow configuration
+      # @return [Hash] The created flow with ID
+      def add_flow(flow)
+        post("/flow", flow)
+      end
+
+      # Get an individual flow configuration
+      #
+      # @param id [String] The flow ID
+      # @return [Hash] Flow configuration
+      def flow(id)
+        get("/flow/#{id}")
+      end
+
+      # Update an individual flow configuration
+      #
+      # @param id [String] The flow ID
+      # @param flow [Hash] The updated flow configuration
+      # @return [Hash] The updated flow
+      def update_flow(id, flow)
+        put("/flow/#{id}", flow)
+      end
+
+      # Delete an individual flow configuration
+      #
+      # @param id [String] The flow ID
+      # @return [Hash] Deletion response
+      def delete_flow(id)
+        delete("/flow/#{id}")
+      end
+
+      # ==================== Node Management ====================
+
+      # Get a list of the installed nodes
+      #
+      # @return [Array<Hash>] List of installed nodes
+      def nodes
+        get("/nodes")
+      end
+
+      # Install a new node module
+      #
+      # @param module_name [String] The name of the node module to install
+      # @return [Hash] Installation response
+      def install_node(module_name)
+        body = { module: module_name }
+        post("/nodes", body)
+      end
+
+      # Get a node module's information
+      #
+      # @param module_name [String] The module name
+      # @return [Hash] Module information
+      def node_module(module_name)
+        get("/nodes/#{module_name}")
+      end
+
+      # Enable or disable a node module
+      #
+      # @param module_name [String] The module name
+      # @param enabled [Boolean] Whether to enable or disable the module
+      # @return [Hash] Update response
+      def update_node_module(module_name, enabled:)
+        body = { enabled: enabled }
+        put("/nodes/#{module_name}", body)
+      end
+
+      # Remove a node module
+      #
+      # @param module_name [String] The module name
+      # @return [Hash] Deletion response
+      def delete_node_module(module_name)
+        delete("/nodes/#{module_name}")
+      end
+
+      # Get a node module set information
+      #
+      # @param module_name [String] The module name
+      # @param set_name [String] The set name
+      # @return [Hash] Node set information
+      def node_set(module_name, set_name)
+        get("/nodes/#{module_name}/#{set_name}")
+      end
+
+      # Enable or disable a node set
+      #
+      # @param module_name [String] The module name
+      # @param set_name [String] The set name
+      # @param enabled [Boolean] Whether to enable or disable the set
+      # @return [Hash] Update response
+      def update_node_set(module_name, set_name, enabled:)
+        body = { enabled: enabled }
+        put("/nodes/#{module_name}/#{set_name}", body)
+      end
+
+      private
+
+      # Perform a GET request
+      #
+      # @param path [String] The API path
+      # @return [Hash, Array] Parsed JSON response
+      def get(path)
+        request(:get, path)
+      end
+
+      # Perform a POST request
+      #
+      # @param path [String] The API path
+      # @param body [Hash] The request body
+      # @param use_auth [Boolean] Whether to use authentication
+      # @return [Hash] Parsed JSON response
+      def post(path, body, use_auth: true)
+        request(:post, path, body: body, use_auth: use_auth)
+      end
+
+      # Perform a PUT request
+      #
+      # @param path [String] The API path
+      # @param body [Hash] The request body
+      # @return [Hash] Parsed JSON response
+      def put(path, body)
+        request(:put, path, body: body)
+      end
+
+      # Perform a DELETE request
+      #
+      # @param path [String] The API path
+      # @return [Hash] Parsed JSON response
+      def delete(path)
+        request(:delete, path)
+      end
+
+      # Perform an HTTP request
+      #
+      # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+      # @param path [String] The API path
+      # @param body [Hash, nil] Optional request body
+      # @param use_auth [Boolean] Whether to use authentication
+      # @return [Hash, Array] Parsed JSON response
+      def request(method, path, body: nil, use_auth: true)
+        uri = URI.join(@base_url, path)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+
+        request = case method
+                  when :get
+                    Net::HTTP::Get.new(uri)
+                  when :post
+                    Net::HTTP::Post.new(uri)
+                  when :put
+                    Net::HTTP::Put.new(uri)
+                  when :delete
+                    Net::HTTP::Delete.new(uri)
+                  else
+                    raise ArgumentError, "Unsupported HTTP method: #{method}"
+                  end
+
+        request["Content-Type"] = "application/json"
+        request["Accept"] = "application/json"
+        request["Authorization"] = "Bearer #{@access_token}" if use_auth && @access_token
+
+        request.body = body.to_json if body
+
+        response = http.request(request)
+        handle_response(response)
+      end
+
+      # Handle the HTTP response
+      #
+      # @param response [Net::HTTPResponse] The HTTP response
+      # @return [Hash, Array] Parsed JSON response
+      # @raise [ApiError, AuthenticationError, NotFoundError, ServerError] Various error types
+      def handle_response(response)
+        case response
+        when Net::HTTPSuccess
+          response.body && !response.body.empty? ? JSON.parse(response.body) : {}
+        when Net::HTTPUnauthorized
+          raise AuthenticationError, "Authentication failed: #{response.code} #{response.message}"
+        when Net::HTTPNotFound
+          raise NotFoundError, "Resource not found: #{response.code} #{response.message}"
+        when Net::HTTPClientError
+          error_message = parse_error_message(response)
+          raise ApiError, "API error: #{response.code} #{error_message}"
+        when Net::HTTPServerError
+          raise ServerError, "Server error: #{response.code} #{response.message}"
+        else
+          raise ApiError, "Unexpected response: #{response.code} #{response.message}"
+        end
+      end
+
+      # Parse error message from response
+      #
+      # @param response [Net::HTTPResponse] The HTTP response
+      # @return [String] Error message
+      def parse_error_message(response)
+        return response.message unless response.body && !response.body.empty?
+
+        begin
+          error_data = JSON.parse(response.body)
+          error_data["message"] || error_data["error"] || response.message
+        rescue JSON::ParserError
+          response.message
+        end
+      end
+    end
+  end
+end

data/lib/node/red/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Node
+  module Red
+    # Base error class for Node-RED API errors
+    class ApiError < StandardError; end
+
+    # Raised when authentication fails
+    class AuthenticationError < ApiError; end
+
+    # Raised when a resource is not found
+    class NotFoundError < ApiError; end
+
+    # Raised when the server returns a 5xx error
+    class ServerError < ApiError; end
+  end
+end

data/lib/node/red/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Node
+  module Red
+    VERSION = "0.1.0"
+  end
+end

data/lib/node/red.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "red/version"
+require_relative "red/errors"
+require_relative "red/client"
+
+module Node
+  module Red
+    class Error < StandardError; end
+  end
+end

data/sig/node/red.rbs

@@ -0,0 +1,6 @@
+module Node
+  module Red
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: node-red
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Davide Santangelo
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-10-28 00:00:00.000000000 Z
+dependencies: []
+description: A comprehensive Ruby wrapper for the Node-RED Admin HTTP API, providing
+  programmatic access to flow management, node management, settings, and authentication.
+email:
+- davide.santangelo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/basic_usage.rb
+- examples/flow_management.rb
+- examples/node_management.rb
+- lib/node/red.rb
+- lib/node/red/client.rb
+- lib/node/red/errors.rb
+- lib/node/red/version.rb
+- sig/node/red.rbs
+homepage: https://github.com/davidesantangelo/node-red
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/davidesantangelo/node-red
+  source_code_uri: https://github.com/davidesantangelo/node-red
+  changelog_uri: https://github.com/davidesantangelo/node-red/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: Ruby client library for Node-RED Admin HTTP API
+test_files: []