keenetic 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fa7552177bec3d537db352ed748bcd24e07bee6156272569a121b7cb18c6a2f
-  data.tar.gz: e48b1c10d4cc62466ebd5e34b200f399e28e8261e0e1a83a1a4b1ee86efc4ee3
+  metadata.gz: cc71a113a4147e3ffd1035596420469ca8c7d9e9639623fd14172b2137d902f6
+  data.tar.gz: 7fcb0cbd7b8a1219715288354b58bfa7a8f15ed7900334be7fd4014a1de9e788
 SHA512:
-  metadata.gz: f801f8df36437d0f2ea76f6765beaeee3a68750b2974b8b3fc4eed9145be5a5c123940245b56566c690ef906d791eaf8223ae3f016b4bb0472c1a2a3476f77df
-  data.tar.gz: 984b84f49fb83117ab0c9c89b60a0b88718ccbbd92258c69987be8103bec4d2fd66554c4413c001e45167396735c634a578e839c35cce74b0124d2d3c829f930
+  metadata.gz: e03cfc9b96ac18afa8ec3526d735970e5381983325920aaf0f771c1e31337f4c0800158a320081c696ad973b75eab29846b961ea5ea76d2c12b6209516a894e4
+  data.tar.gz: fba387ac8b75676298f75715b22c1c348d3ca749fe44234b2c0dbd8d01ff6b9554f78ddf19fcea2b4dcfbee17ccadc253f91a5c777c7c91427d89140fab5335e

data/README.md

@@ -20,62 +20,36 @@ Keenetic.configure do |config|
 end
 ```
 
-## Usage
+## Quick Start
 
 ```ruby
 client = Keenetic.client
 
-# Connected devices
-client.devices.all
-client.devices.active
-client.devices.find(mac: 'AA:BB:CC:DD:EE:FF')
-client.devices.update(mac: 'AA:BB:CC:DD:EE:FF', name: 'My Phone')
-
 # System info
-client.system.info       # model, firmware
-client.system.resources  # CPU, memory, uptime
+client.system.info              # model, firmware
+client.system.resources         # CPU, memory, uptime
+
+# Connected devices
+client.devices.all              # all registered devices
+client.devices.active           # currently connected
 
 # Network
-client.network.interfaces
-
-# WiFi
-client.wifi.access_points
-client.wifi.clients
-
-# Internet
-client.internet.status
-client.internet.speed
-
-# Ports
-client.ports.all
-
-# Static Routes
-client.routes.all
-client.routes.add(host: '1.2.3.4', interface: 'Wireguard0', comment: 'VPN host')
-client.routes.add(network: '10.0.0.0/24', interface: 'Wireguard0', comment: 'VPN network')
-client.routes.add_batch([
-  { host: '1.2.3.4', interface: 'Wireguard0', comment: 'Host 1' },
-  { network: '10.0.0.0/24', interface: 'Wireguard0', comment: 'Network 1' }
-])
-client.routes.delete(host: '1.2.3.4')
-client.routes.delete(network: '10.0.0.0/24')
-
-# Hotspot / Policies
-client.hotspot.policies                                         # all IP policies
-client.hotspot.hosts                                            # all registered hosts
-client.hotspot.set_host_policy(mac: 'AA:BB:CC:DD:EE:FF', policy: 'Policy0')
-client.hotspot.set_host_policy(mac: 'AA:BB:CC:DD:EE:FF', policy: nil)  # remove policy
+client.network.interfaces       # all interfaces
+client.wifi.access_points       # Wi-Fi networks
+client.internet.status          # internet connectivity
+
+# Port forwarding
+client.nat.rules                # NAT rules
+client.nat.add_forward(index: 1, protocol: 'tcp', port: 8080, 
+                       to_host: '192.168.1.100', to_port: 80)
+
+# VPN
+client.vpn.status               # VPN server status
+client.vpn.clients              # connected VPN clients
 
 # Configuration
 client.system_config.save       # save to flash
-client.system_config.download   # download startup-config.txt
-
-# Raw RCI Access (for custom commands)
-client.rci({ 'show' => { 'system' => {} } })
-client.rci([
-  { 'show' => { 'system' => {} } },
-  { 'show' => { 'version' => {} } }
-])
+client.system_config.download   # backup config
 ```
 
 ## Error Handling
@@ -89,18 +63,18 @@ rescue Keenetic::ConnectionError
   # router unreachable
 rescue Keenetic::TimeoutError
   # request timed out
-rescue Keenetic::NotFoundError
-  # resource not found
 rescue Keenetic::ApiError => e
-  # Other API errors
+  # other API errors
   e.status_code
   e.response_body
 end
 ```
 
-## API Reference
+## Documentation
 
-See [KEENETIC_API.md](KEENETIC_API.md) for complete API documentation.
+- [Complete API Reference](docs/API_REFERENCE.md) - All features with detailed examples
+- [API Coverage](API_PROGRESS.md) - Implementation status
+- [Keenetic API Specification](KEENETIC_API.md) - Raw API documentation
 
 ## Requirements
 

data/lib/keenetic/client.rb

@@ -117,6 +117,71 @@ module Keenetic
       @system_config ||= Resources::Config.new(self)
     end
 
+    # @return [Resources::Nat] NAT and port forwarding resource
+    def nat
+      @nat ||= Resources::Nat.new(self)
+    end
+
+    # @return [Resources::Vpn] VPN server resource
+    def vpn
+      @vpn ||= Resources::Vpn.new(self)
+    end
+
+    # @return [Resources::Diagnostics] Network diagnostics resource
+    def diagnostics
+      @diagnostics ||= Resources::Diagnostics.new(self)
+    end
+
+    # @return [Resources::Firewall] Firewall resource
+    def firewall
+      @firewall ||= Resources::Firewall.new(self)
+    end
+
+    # @return [Resources::Mesh] Mesh Wi-Fi system resource
+    def mesh
+      @mesh ||= Resources::Mesh.new(self)
+    end
+
+    # @return [Resources::Usb] USB devices and storage resource
+    def usb
+      @usb ||= Resources::Usb.new(self)
+    end
+
+    # @return [Resources::Dns] DNS settings and cache resource
+    def dns
+      @dns ||= Resources::Dns.new(self)
+    end
+
+    # @return [Resources::Dyndns] Dynamic DNS resource
+    def dyndns
+      @dyndns ||= Resources::Dyndns.new(self)
+    end
+
+    # @return [Resources::Schedule] Access schedules resource
+    def schedule
+      @schedule ||= Resources::Schedule.new(self)
+    end
+
+    # @return [Resources::Users] User accounts resource
+    def users
+      @users ||= Resources::Users.new(self)
+    end
+
+    # @return [Resources::Components] System components resource
+    def components
+      @components ||= Resources::Components.new(self)
+    end
+
+    # @return [Resources::Qos] QoS and traffic control resource
+    def qos
+      @qos ||= Resources::Qos.new(self)
+    end
+
+    # @return [Resources::Ipv6] IPv6 network resource
+    def ipv6
+      @ipv6 ||= Resources::Ipv6.new(self)
+    end
+
     # Execute arbitrary RCI command(s).
     #
     # Provides raw access to the Keenetic RCI (Remote Command Interface).
@@ -211,6 +276,19 @@ module Keenetic
       request(:post, '/rci/', body: commands)
     end
 
+    # Make a POST request with raw body content (non-JSON).
+    #
+    # Used for file uploads like configuration restore.
+    #
+    # @param path [String] API path
+    # @param content [String] Raw content to send
+    # @param content_type [String] Content-Type header (default: text/plain)
+    # @return [String, nil] Response body
+    #
+    def post_raw(path, content, content_type: 'text/plain')
+      request(:post, path, raw_body: content, content_type: content_type)
+    end
+
     # Check if client is authenticated.
     # @return [Boolean]
     def authenticated?
@@ -254,7 +332,10 @@ module Keenetic
         url += "?#{URI.encode_www_form(options[:params])}"
       end
 
-      if options[:body]
+      if options[:raw_body]
+        request_options[:body] = options[:raw_body]
+        request_options[:headers]['Content-Type'] = options[:content_type] || 'text/plain'
+      elsif options[:body]
         request_options[:body] = options[:body].to_json
         request_options[:headers]['Content-Type'] = 'application/json'
       end

data/lib/keenetic/resources/base.rb

@@ -17,6 +17,10 @@ module Keenetic
         client.post(path, body)
       end
 
+      def post_raw(path, content, content_type: 'text/plain')
+        client.post_raw(path, content, content_type: content_type)
+      end
+
       # Convert kebab-case keys to snake_case symbols
       # @param hash [Hash] Hash with string keys
       # @return [Hash] Hash with symbolized snake_case keys

data/lib/keenetic/resources/components.rb

@@ -0,0 +1,88 @@
+module Keenetic
+  module Resources
+    # Components resource for managing installable router components.
+    #
+    # == API Endpoints Used
+    #
+    # === Installed Components
+    #   GET /rci/show/components
+    #
+    # === Available Components
+    #   GET /rci/show/components/available
+    #
+    # === Install Component
+    #   POST /rci/components/install
+    #
+    # === Remove Component
+    #   POST /rci/components/remove
+    #
+    class Components < Base
+      # Get installed components.
+      #
+      # @return [Array<Hash>] List of installed components
+      # @example
+      #   installed = client.components.installed
+      #
+      def installed
+        response = get('/rci/show/components')
+        normalize_components(response)
+      end
+
+      # Get available components for installation.
+      #
+      # @return [Array<Hash>] List of available components
+      # @example
+      #   available = client.components.available
+      #
+      def available
+        response = get('/rci/show/components/available')
+        normalize_components(response)
+      end
+
+      # Install a component.
+      #
+      # @param name [String] Component name
+      # @return [Hash, nil] API response
+      # @example
+      #   client.components.install(name: 'transmission')
+      #
+      def install(name:)
+        post('/rci/components/install', { 'name' => name })
+      end
+
+      # Remove a component.
+      #
+      # @param name [String] Component name
+      # @return [Hash, nil] API response
+      # @example
+      #   client.components.remove(name: 'transmission')
+      #
+      def remove(name:)
+        post('/rci/components/remove', { 'name' => name })
+      end
+
+      private
+
+      def normalize_components(response)
+        components_data = case response
+                          when Array
+                            response
+                          when Hash
+                            response['component'] || response['components'] || []
+                          else
+                            []
+                          end
+
+        return [] unless components_data.is_a?(Array)
+
+        components_data.map { |component| normalize_component(component) }.compact
+      end
+
+      def normalize_component(data)
+        return nil unless data.is_a?(Hash)
+
+        deep_normalize_keys(data)
+      end
+    end
+  end
+end

data/lib/keenetic/resources/config.rb

@@ -13,6 +13,11 @@ module Keenetic
     #   GET /ci/startup-config.txt
     #   Returns: Plain text configuration file
     #
+    # === Upload Configuration
+    #   POST /ci/startup-config.txt
+    #   Body: Plain text configuration file
+    #   Restores configuration from backup
+    #
     class Config < Base
       # Save current configuration to persistent storage.
       #
@@ -42,12 +47,43 @@ module Keenetic
       #
       # @return [String] Configuration file content
       # @example
-      #   config_text = client.config.download
+      #   config_text = client.system_config.download
       #   File.write('router-backup.txt', config_text)
       #
       def download
         get('/ci/startup-config.txt')
       end
+
+      # Upload and restore a configuration file.
+      #
+      # == Keenetic API Request
+      #   POST /ci/startup-config.txt
+      #   Content-Type: text/plain
+      #   Body: Configuration file content
+      #
+      # Uploads a configuration file to the router. The configuration
+      # will be applied after a reboot.
+      #
+      # == Warning
+      # This is a potentially destructive operation. Uploading an
+      # invalid or incompatible configuration may make the router
+      # inaccessible. Always ensure you have physical access to the
+      # router before restoring configuration.
+      #
+      # @param content [String] Configuration file content
+      # @return [String, nil] Response from the router
+      # @example Upload from string
+      #   client.system_config.upload(config_text)
+      #
+      # @example Upload from file
+      #   config_text = File.read('router-backup.txt')
+      #   client.system_config.upload(config_text)
+      #
+      def upload(content)
+        raise ArgumentError, 'Configuration content cannot be empty' if content.nil? || content.strip.empty?
+
+        post_raw('/ci/startup-config.txt', content)
+      end
     end
   end
 end

data/lib/keenetic/resources/diagnostics.rb

@@ -0,0 +1,102 @@
+module Keenetic
+  module Resources
+    # Diagnostics resource for network troubleshooting tools.
+    #
+    # == API Endpoints Used
+    #
+    # === Ping
+    #   POST /rci/tools/ping
+    #   Body: { host, count }
+    #
+    # === Traceroute
+    #   POST /rci/tools/traceroute
+    #   Body: { host }
+    #
+    # === DNS Lookup
+    #   POST /rci/tools/nslookup
+    #   Body: { host }
+    #
+    class Diagnostics < Base
+      # Ping a host from the router.
+      #
+      # == Keenetic API Request
+      #   POST /rci/tools/ping
+      #   Body: { "host": "8.8.8.8", "count": 4 }
+      #
+      # @param host [String] Hostname or IP address to ping
+      # @param count [Integer] Number of ping packets (default: 4)
+      # @return [Hash] Ping results
+      #
+      # @example Ping Google DNS
+      #   result = client.diagnostics.ping('8.8.8.8')
+      #   # => { host: "8.8.8.8", transmitted: 4, received: 4, loss: 0, ... }
+      #
+      # @example Ping with custom count
+      #   result = client.diagnostics.ping('google.com', count: 10)
+      #
+      def ping(host, count: 4)
+        response = post('/rci/tools/ping', { 'host' => host, 'count' => count })
+        normalize_ping_result(response)
+      end
+
+      # Trace route to a host from the router.
+      #
+      # == Keenetic API Request
+      #   POST /rci/tools/traceroute
+      #   Body: { "host": "google.com" }
+      #
+      # @param host [String] Hostname or IP address to trace
+      # @return [Hash] Traceroute results with hops
+      #
+      # @example Trace route to Google
+      #   result = client.diagnostics.traceroute('google.com')
+      #   # => { host: "google.com", hops: [{ hop: 1, ip: "192.168.1.1", time: 1 }, ...] }
+      #
+      def traceroute(host)
+        response = post('/rci/tools/traceroute', { 'host' => host })
+        normalize_traceroute_result(response)
+      end
+
+      # Perform DNS lookup from the router.
+      #
+      # == Keenetic API Request
+      #   POST /rci/tools/nslookup
+      #   Body: { "host": "google.com" }
+      #
+      # @param host [String] Hostname to resolve
+      # @return [Hash] DNS lookup results
+      #
+      # @example Lookup Google
+      #   result = client.diagnostics.nslookup('google.com')
+      #   # => { host: "google.com", addresses: ["142.250.185.46", ...], ... }
+      #
+      def nslookup(host)
+        response = post('/rci/tools/nslookup', { 'host' => host })
+        normalize_nslookup_result(response)
+      end
+
+      # Alias for nslookup
+      alias dns_lookup nslookup
+
+      private
+
+      def normalize_ping_result(response)
+        return {} unless response.is_a?(Hash)
+
+        deep_normalize_keys(response)
+      end
+
+      def normalize_traceroute_result(response)
+        return {} unless response.is_a?(Hash)
+
+        deep_normalize_keys(response)
+      end
+
+      def normalize_nslookup_result(response)
+        return {} unless response.is_a?(Hash)
+
+        deep_normalize_keys(response)
+      end
+    end
+  end
+end

data/lib/keenetic/resources/dns.rb

@@ -0,0 +1,95 @@
+module Keenetic
+  module Resources
+    # DNS resource for managing DNS settings and cache.
+    #
+    # == API Endpoints Used
+    #
+    # === Reading DNS Servers
+    #   GET /rci/show/ip/name-server
+    #   Returns: Configured DNS servers
+    #
+    # === Reading DNS Cache
+    #   GET /rci/show/dns/cache
+    #   Returns: DNS cache entries
+    #
+    # === Reading DNS Proxy Settings
+    #   GET /rci/show/dns/proxy
+    #   Returns: DNS proxy configuration
+    #
+    # === Clear DNS Cache
+    #   POST /rci/dns/cache/clear
+    #   Body: {}
+    #
+    class Dns < Base
+      # Get configured DNS servers.
+      #
+      # == Keenetic API Request
+      #   GET /rci/show/ip/name-server
+      #
+      # @return [Hash] DNS servers configuration
+      # @example
+      #   servers = client.dns.servers
+      #
+      def servers
+        response = get('/rci/show/ip/name-server')
+        normalize_response(response)
+      end
+
+      # Alias for servers
+      alias name_servers servers
+
+      # Get DNS cache entries.
+      #
+      # == Keenetic API Request
+      #   GET /rci/show/dns/cache
+      #
+      # @return [Hash] DNS cache data
+      # @example
+      #   cache = client.dns.cache
+      #
+      def cache
+        response = get('/rci/show/dns/cache')
+        normalize_response(response)
+      end
+
+      # Get DNS proxy settings.
+      #
+      # == Keenetic API Request
+      #   GET /rci/show/dns/proxy
+      #
+      # @return [Hash] DNS proxy configuration
+      # @example
+      #   proxy = client.dns.proxy
+      #
+      def proxy
+        response = get('/rci/show/dns/proxy')
+        normalize_response(response)
+      end
+
+      # Alias for proxy
+      alias proxy_settings proxy
+
+      # Clear DNS cache.
+      #
+      # == Keenetic API Request
+      #   POST /rci/dns/cache/clear
+      #   Body: {}
+      #
+      # @return [Hash, nil] API response
+      # @example
+      #   client.dns.clear_cache
+      #
+      def clear_cache
+        post('/rci/dns/cache/clear', {})
+      end
+
+      private
+
+      def normalize_response(response)
+        return {} unless response.is_a?(Hash)
+
+        deep_normalize_keys(response)
+      end
+    end
+  end
+end

data/lib/keenetic/resources/dyndns.rb

@@ -0,0 +1,71 @@
+module Keenetic
+  module Resources
+    # Dynamic DNS resource for managing KeenDNS and third-party DDNS.
+    #
+    # == API Endpoints Used
+    #
+    # === KeenDNS Status
+    #   GET /rci/show/rc/ip/http/dyndns
+    #
+    # === Configure KeenDNS
+    #   POST /rci/ip/http/dyndns
+    #
+    # === Third-Party DDNS
+    #   GET /rci/show/dyndns
+    #
+    class Dyndns < Base
+      # Get KeenDNS status.
+      #
+      # @return [Hash] KeenDNS configuration and status
+      # @example
+      #   status = client.dyndns.keendns_status
+      #
+      def keendns_status
+        response = get('/rci/show/rc/ip/http/dyndns')
+        normalize_response(response)
+      end
+
+      # Configure KeenDNS.
+      #
+      # @param params [Hash] KeenDNS configuration parameters
+      # @return [Hash, nil] API response
+      # @example
+      #   client.dyndns.configure_keendns(enabled: true, domain: 'myrouter')
+      #
+      def configure_keendns(**params)
+        post('/rci/ip/http/dyndns', normalize_params(params))
+      end
+
+      # Get third-party DDNS providers status.
+      #
+      # @return [Hash] Third-party DDNS configuration
+      # @example
+      #   ddns = client.dyndns.third_party
+      #
+      def third_party
+        response = get('/rci/show/dyndns')
+        normalize_response(response)
+      end
+
+      # Alias for third_party
+      alias providers third_party
+
+      private
+
+      def normalize_response(response)
+        return {} unless response.is_a?(Hash)
+
+        deep_normalize_keys(response)
+      end
+
+      def normalize_params(params)
+        result = {}
+        params.each do |key, value|
+          api_key = key.to_s.tr('_', '-')
+          result[api_key] = value
+        end
+        result
+      end
+    end
+  end
+end