keenetic 0.1.0 → 1.0.0

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

data/lib/keenetic/resources/firewall.rb

@@ -0,0 +1,103 @@
+module Keenetic
+  module Resources
+    # Firewall resource for managing firewall policies and access lists.
+    #
+    # == API Endpoints Used
+    #
+    # === Reading Firewall Policies
+    #   GET /rci/show/ip/policy
+    #   Returns: Firewall policy configuration
+    #
+    # === Reading Access Lists
+    #   GET /rci/show/access-list
+    #   Returns: Access control lists
+    #
+    # === Adding Firewall Rule
+    #   POST /rci/ip/policy
+    #   Body: Rule configuration
+    #
+    class Firewall < Base
+      # Get firewall policies.
+      #
+      # == Keenetic API Request
+      #   GET /rci/show/ip/policy
+      #
+      # @return [Hash] Firewall policy configuration
+      # @example
+      #   policies = client.firewall.policies
+      #
+      def policies
+        response = get('/rci/show/ip/policy')
+        normalize_response(response)
+      end
+
+      # Get access control lists.
+      #
+      # == Keenetic API Request
+      #   GET /rci/show/access-list
+      #
+      # @return [Hash] Access lists configuration
+      # @example
+      #   lists = client.firewall.access_lists
+      #
+      def access_lists
+        response = get('/rci/show/access-list')
+        normalize_response(response)
+      end
+
+      # Add a firewall rule.
+      #
+      # == Keenetic API Request
+      #   POST /rci/ip/policy
+      #
+      # @param params [Hash] Rule configuration
+      # @return [Hash, nil] API response
+      #
+      # @example Add a basic rule
+      #   client.firewall.add_rule(
+      #     action: 'permit',
+      #     protocol: 'tcp',
+      #     src: '192.168.1.0/24',
+      #     dst_port: 80
+      #   )
+      #
+      def add_rule(**params)
+        post('/rci/ip/policy', normalize_params(params))
+      end
+
+      # Delete a firewall rule.
+      #
+      # == Keenetic API Request
+      #   POST /rci/ip/policy
+      #   Body: { index, no: true }
+      #
+      # @param index [Integer] Rule index to delete
+      # @return [Hash, nil] API response
+      #
+      # @example
+      #   client.firewall.delete_rule(index: 1)
+      #
+      def delete_rule(index:)
+        post('/rci/ip/policy', { 'index' => index, 'no' => true })
+      end
+
+      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|
+          # Convert snake_case to kebab-case for API
+          api_key = key.to_s.tr('_', '-')
+          result[api_key] = value
+        end
+        result
+      end
+    end
+  end
+end

data/lib/keenetic/resources/hotspot.rb

@@ -0,0 +1,282 @@
+module Keenetic
+  module Resources
+    # Manages hotspot hosts and IP policies.
+    #
+    # == API Endpoints Used
+    #
+    # === Reading Policies
+    #   POST /rci/ (batch format)
+    #   Body: [{"show": {"sc": {"ip": {"policy": {}}}}}]
+    #   Returns: All IP policies from configuration
+    #
+    # === Reading Hosts
+    #   POST /rci/ (batch format)
+    #   Body: [
+    #     {"show": {"sc": {"ip": {"hotspot": {"host": {}}}}}},
+    #     {"show": {"ip": {"hotspot": {}}}}
+    #   ]
+    #   Returns: Configuration hosts and runtime hosts
+    #
+    # === Setting Host Policy
+    #   POST /rci/ (batch format)
+    #   Body: [
+    #     {"webhelp": {"event": {"push": {"data": "..."}}}},
+    #     {"ip": {"hotspot": {"host": {"mac": "...", "permit": true, "policy": "..."}}}},
+    #     {"system": {"configuration": {"save": {}}}}
+    #   ]
+    #
+    class Hotspot < Base
+      # Get all IP policies.
+      #
+      # == Keenetic API Request
+      #   POST /rci/ (batch format)
+      #   Body: [{"show": {"sc": {"ip": {"policy": {}}}}}]
+      #
+      # == Response Structure from API
+      #   [
+      #     {
+      #       "id": "Policy0",
+      #       "description": "VPN Policy",
+      #       "global": false,
+      #       "interface": [
+      #         { "name": "Wireguard0", "priority": 100 }
+      #       ]
+      #     }
+      #   ]
+      #
+      # @return [Array<Hash>] List of normalized policy hashes
+      # @example
+      #   policies = client.hotspot.policies
+      #   # => [{ id: "Policy0", description: "VPN Policy", global: false, interfaces: [...] }]
+      #
+      def policies
+        response = client.batch([{ 'show' => { 'sc' => { 'ip' => { 'policy' => {} } } } }])
+        policies_data = extract_policies_from_response(response)
+        normalize_policies(policies_data)
+      end
+
+      # Get all registered hosts with their policies.
+      #
+      # == Keenetic API Request
+      #   POST /rci/ (batch format)
+      #   Body: [
+      #     {"show": {"sc": {"ip": {"hotspot": {"host": {}}}}}},
+      #     {"show": {"ip": {"hotspot": {}}}}
+      #   ]
+      #
+      # Returns merged data from configuration (static settings) and runtime (current status).
+      #
+      # @return [Array<Hash>] List of normalized host hashes
+      # @example
+      #   hosts = client.hotspot.hosts
+      #   # => [{ mac: "AA:BB:CC:DD:EE:FF", name: "My Device", policy: "Policy0", permit: true, ... }]
+      #
+      def hosts
+        response = client.batch([
+          { 'show' => { 'sc' => { 'ip' => { 'hotspot' => { 'host' => {} } } } } },
+          { 'show' => { 'ip' => { 'hotspot' => {} } } }
+        ])
+
+        config_hosts = extract_config_hosts(response)
+        runtime_hosts = extract_runtime_hosts(response)
+
+        merge_hosts(config_hosts, runtime_hosts)
+      end
+
+      # Set or remove policy for a host.
+      #
+      # == Keenetic API Request
+      #   POST /rci/ (batch format)
+      #   Body: [
+      #     {"webhelp": {"event": {"push": {"data": "{\"type\":\"configuration_change\",\"value\":{\"url\":\"/policies/policy-consumers\"}}"}}}},
+      #     {"ip": {"hotspot": {"host": {"mac": "...", "permit": true, "policy": "..."}}}},
+      #     {"system": {"configuration": {"save": {}}}}
+      #   ]
+      #
+      # @param mac [String] Client MAC address (required)
+      # @param policy [String, nil] Policy name (e.g., "Policy0"), or nil to remove policy
+      # @param permit [Boolean] Whether to permit the host (default: true)
+      # @return [Array<Hash>] API response
+      #
+      # @example Assign policy to host
+      #   client.hotspot.set_host_policy(mac: "AA:BB:CC:DD:EE:FF", policy: "Policy0")
+      #
+      # @example Remove policy from host
+      #   client.hotspot.set_host_policy(mac: "AA:BB:CC:DD:EE:FF", policy: nil)
+      #
+      # @example Assign policy with deny access
+      #   client.hotspot.set_host_policy(mac: "AA:BB:CC:DD:EE:FF", policy: "Policy0", permit: false)
+      #
+      def set_host_policy(mac:, policy:, permit: true)
+        raise ArgumentError, 'MAC address is required' if mac.nil? || mac.to_s.strip.empty?
+
+        normalized_mac = mac.downcase
+
+        host_params = {
+          'mac' => normalized_mac,
+          'permit' => permit
+        }
+
+        if policy.nil? || policy.to_s.strip.empty?
+          # Remove policy assignment
+          host_params['policy'] = { 'no' => true }
+        else
+          host_params['policy'] = policy
+        end
+
+        commands = [
+          webhelp_event,
+          { 'ip' => { 'hotspot' => { 'host' => host_params } } },
+          save_config_command
+        ]
+
+        client.batch(commands)
+      end
+
+      # Find a specific policy by ID.
+      #
+      # @param id [String] Policy ID (e.g., "Policy0")
+      # @return [Hash, nil] Policy data or nil if not found
+      # @example
+      #   policy = client.hotspot.find_policy(id: "Policy0")
+      #   # => { id: "Policy0", description: "VPN Policy", ... }
+      #
+      def find_policy(id:)
+        policies.find { |p| p[:id] == id }
+      end
+
+      # Find a specific host by MAC address.
+      #
+      # @param mac [String] MAC address (case-insensitive)
+      # @return [Hash, nil] Host data or nil if not found
+      # @example
+      #   host = client.hotspot.find_host(mac: "AA:BB:CC:DD:EE:FF")
+      #   # => { mac: "AA:BB:CC:DD:EE:FF", name: "My Device", policy: "Policy0", ... }
+      #
+      def find_host(mac:)
+        hosts.find { |h| h[:mac]&.downcase == mac.downcase }
+      end
+
+      private
+
+      def extract_policies_from_response(response)
+        return [] unless response.is_a?(Array) && response.first.is_a?(Hash)
+
+        response.dig(0, 'show', 'sc', 'ip', 'policy') || []
+      end
+
+      def extract_config_hosts(response)
+        return [] unless response.is_a?(Array) && response[0].is_a?(Hash)
+
+        hosts = response.dig(0, 'show', 'sc', 'ip', 'hotspot', 'host') || []
+        hosts.is_a?(Array) ? hosts : [hosts]
+      end
+
+      def extract_runtime_hosts(response)
+        return [] unless response.is_a?(Array) && response[1].is_a?(Hash)
+
+        hosts = response.dig(1, 'show', 'ip', 'hotspot', 'host') || []
+        hosts.is_a?(Array) ? hosts : [hosts]
+      end
+
+      def normalize_policies(policies_data)
+        return [] unless policies_data.is_a?(Array)
+
+        policies_data.map { |policy| normalize_policy(policy) }.compact
+      end
+
+      def normalize_policy(data)
+        return nil unless data.is_a?(Hash)
+
+        interfaces = data['interface'] || []
+        interfaces = [interfaces] unless interfaces.is_a?(Array)
+
+        {
+          id: data['id'],
+          description: data['description'],
+          global: normalize_boolean(data['global']),
+          interfaces: interfaces.map { |iface| normalize_policy_interface(iface) }.compact
+        }
+      end
+
+      def normalize_policy_interface(data)
+        return nil unless data.is_a?(Hash)
+
+        {
+          name: data['name'],
+          priority: data['priority']
+        }
+      end
+
+      def merge_hosts(config_hosts, runtime_hosts)
+        # Create lookup from runtime hosts by MAC
+        runtime_by_mac = runtime_hosts.each_with_object({}) do |host, lookup|
+          next unless host.is_a?(Hash) && host['mac']
+
+          lookup[host['mac'].upcase] = host
+        end
+
+        # Process config hosts and merge with runtime data
+        all_hosts = config_hosts.map do |config_host|
+          next unless config_host.is_a?(Hash) && config_host['mac']
+
+          mac = config_host['mac'].upcase
+          runtime_host = runtime_by_mac.delete(mac) || {}
+          normalize_host(config_host, runtime_host)
+        end.compact
+
+        # Add any remaining runtime-only hosts
+        runtime_by_mac.values.each do |runtime_host|
+          all_hosts << normalize_host({}, runtime_host)
+        end
+
+        all_hosts
+      end
+
+      def normalize_host(config_data, runtime_data)
+        config_data ||= {}
+        runtime_data ||= {}
+
+        mac = config_data['mac'] || runtime_data['mac']
+        return nil unless mac
+
+        {
+          mac: mac.upcase,
+          name: config_data['name'] || runtime_data['name'] || runtime_data['hostname'],
+          hostname: runtime_data['hostname'],
+          ip: runtime_data['ip'],
+          interface: runtime_data['interface'],
+          via: runtime_data['via'],
+          policy: config_data['policy'],
+          permit: normalize_boolean(config_data['permit']),
+          deny: normalize_boolean(config_data['deny']),
+          schedule: config_data['schedule'],
+          active: normalize_boolean(runtime_data['active']),
+          registered: normalize_boolean(runtime_data['registered']),
+          access: runtime_data['access'],
+          rxbytes: runtime_data['rxbytes'],
+          txbytes: runtime_data['txbytes'],
+          uptime: runtime_data['uptime'],
+          first_seen: runtime_data['first-seen'],
+          last_seen: runtime_data['last-seen']
+        }
+      end
+
+      def webhelp_event
+        {
+          'webhelp' => {
+            'event' => {
+              'push' => {
+                'data' => '{"type":"configuration_change","value":{"url":"/policies/policy-consumers"}}'
+              }
+            }
+          }
+        }
+      end
+
+      def save_config_command
+        { 'system' => { 'configuration' => { 'save' => {} } } }
+      end
+    end
+  end
+end

data/lib/keenetic/resources/ipv6.rb

@@ -0,0 +1,74 @@
+module Keenetic
+  module Resources
+    # IPv6 resource for IPv6 network information.
+    #
+    # == API Endpoints Used
+    #
+    # === IPv6 Interfaces
+    #   GET /rci/show/ipv6/interface
+    #
+    # === IPv6 Routes
+    #   GET /rci/show/ipv6/route
+    #
+    # === IPv6 Neighbors
+    #   GET /rci/show/ipv6/neighbor
+    #
+    class Ipv6 < Base
+      # Get IPv6 interfaces.
+      #
+      # @return [Array<Hash>] List of IPv6 interfaces
+      # @example
+      #   interfaces = client.ipv6.interfaces
+      #
+      def interfaces
+        response = get('/rci/show/ipv6/interface')
+        normalize_list(response, 'interface')
+      end
+
+      # Get IPv6 routing table.
+      #
+      # @return [Array<Hash>] List of IPv6 routes
+      # @example
+      #   routes = client.ipv6.routes
+      #
+      def routes
+        response = get('/rci/show/ipv6/route')
+        normalize_list(response, 'route')
+      end
+
+      # Get IPv6 neighbor table (NDP cache).
+      #
+      # @return [Array<Hash>] List of IPv6 neighbors
+      # @example
+      #   neighbors = client.ipv6.neighbors
+      #
+      def neighbors
+        response = get('/rci/show/ipv6/neighbor')
+        normalize_list(response, 'neighbor')
+      end
+
+      private
+
+      def normalize_list(response, key)
+        data = case response
+               when Array
+                 response
+               when Hash
+                 response[key] || response["#{key}s"] || []
+               else
+                 []
+               end
+
+        return [] unless data.is_a?(Array)
+
+        data.map { |item| normalize_item(item) }.compact
+      end
+
+      def normalize_item(data)
+        return nil unless data.is_a?(Hash)
+
+        deep_normalize_keys(data)
+      end
+    end
+  end
+end

data/lib/keenetic/resources/mesh.rb

@@ -0,0 +1,84 @@
+module Keenetic
+  module Resources
+    # Mesh resource for monitoring mesh Wi-Fi system status.
+    #
+    # == API Endpoints Used
+    #
+    # === Reading Mesh Status
+    #   GET /rci/show/mws
+    #   Returns: Mesh Wi-Fi system status and configuration
+    #
+    # === Reading Mesh Members
+    #   GET /rci/show/mws/member
+    #   Returns: Connected mesh nodes/extenders
+    #
+    class Mesh < Base
+      # Get mesh Wi-Fi system status.
+      #
+      # == Keenetic API Request
+      #   GET /rci/show/mws
+      #
+      # @return [Hash] Mesh system status and configuration
+      # @example
+      #   status = client.mesh.status
+      #   # => { enabled: true, role: "controller", members_count: 2, ... }
+      #
+      def status
+        response = get('/rci/show/mws')
+        normalize_status(response)
+      end
+
+      # Get connected mesh members (nodes/extenders).
+      #
+      # == Keenetic API Request
+      #   GET /rci/show/mws/member
+      #
+      # @return [Array<Hash>] List of mesh members
+      # @example
+      #   members = client.mesh.members
+      #   # => [
+      #   #   { mac: "AA:BB:CC:DD:EE:FF", name: "Living Room", mode: "extender", ... },
+      #   #   ...
+      #   # ]
+      #
+      def members
+        response = get('/rci/show/mws/member')
+        normalize_members(response)
+      end
+
+      private
+
+      def normalize_status(response)
+        return {} unless response.is_a?(Hash)
+
+        result = deep_normalize_keys(response)
+        normalize_booleans(result, %i[enabled active])
+        result
+      end
+
+      def normalize_members(response)
+        # Response might be array directly or wrapped in an object
+        members_data = case response
+                       when Array
+                         response
+                       when Hash
+                         response['member'] || response['members'] || []
+                       else
+                         []
+                       end
+
+        return [] unless members_data.is_a?(Array)
+
+        members_data.map { |member| normalize_member(member) }.compact
+      end
+
+      def normalize_member(data)
+        return nil unless data.is_a?(Hash)
+
+        result = deep_normalize_keys(data)
+        normalize_booleans(result, %i[online active connected])
+        result
+      end
+    end
+  end
+end