keenetic 0.2.0 → 1.0.0

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/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

data/lib/keenetic/resources/nat.rb

@@ -0,0 +1,202 @@
+module Keenetic
+  module Resources
+    # NAT resource for managing port forwarding rules.
+    #
+    # == API Endpoints Used
+    #
+    # === Reading NAT Rules
+    #   GET /rci/show/ip/nat
+    #   Returns: Array of port forwarding rules
+    #
+    # === Adding Port Forward
+    #   POST /rci/ip/nat
+    #   Body: { index, description, protocol, interface, port, to-host, to-port, enabled }
+    #
+    # === Deleting Port Forward
+    #   POST /rci/ip/nat
+    #   Body: { index, no: true }
+    #
+    # === Reading UPnP Mappings
+    #   GET /rci/show/upnp/redirect
+    #   Returns: Array of automatic UPnP port mappings
+    #
+    class Nat < Base
+      # Get all NAT/port forwarding rules.
+      #
+      # == Keenetic API Request
+      #   GET /rci/show/ip/nat
+      #
+      # == Response Fields
+      #   - index: Rule index/priority
+      #   - description: Rule description
+      #   - protocol: "tcp", "udp", or "any"
+      #   - interface: WAN interface
+      #   - port: External port
+      #   - end_port: End of port range (optional)
+      #   - to_host: Internal host IP
+      #   - to_port: Internal port
+      #   - enabled: Rule is active
+      #
+      # @return [Array<Hash>] List of normalized NAT rules
+      # @example
+      #   rules = client.nat.rules
+      #   # => [{ index: 1, description: "Web Server", protocol: "tcp", port: 8080, ... }]
+      #
+      def rules
+        response = get('/rci/show/ip/nat')
+        normalize_rules(response)
+      end
+
+      # Find a NAT rule by index.
+      #
+      # @param index [Integer] Rule index
+      # @return [Hash, nil] Rule data or nil if not found
+      # @example
+      #   rule = client.nat.find_rule(1)
+      #   # => { index: 1, description: "Web Server", ... }
+      #
+      def find_rule(index)
+        rules.find { |r| r[:index] == index }
+      end
+
+      # Add a port forwarding rule.
+      #
+      # == Keenetic API Request
+      #   POST /rci/ip/nat
+      #   Body: { index, description, protocol, interface, port, to-host, to-port, enabled }
+      #
+      # @param index [Integer] Rule index/priority
+      # @param protocol [String] Protocol: "tcp", "udp", or "any"
+      # @param port [Integer] External port
+      # @param to_host [String] Internal host IP address
+      # @param to_port [Integer] Internal port
+      # @param interface [String] WAN interface name (default: "ISP")
+      # @param description [String, nil] Optional rule description
+      # @param end_port [Integer, nil] End of port range (optional)
+      # @param enabled [Boolean] Whether rule is active (default: true)
+      # @return [Hash, Array, nil] API response
+      #
+      # @example Add simple port forward
+      #   client.nat.add_forward(
+      #     index: 1,
+      #     protocol: 'tcp',
+      #     port: 8080,
+      #     to_host: '192.168.1.100',
+      #     to_port: 80
+      #   )
+      #
+      # @example Add port range forward
+      #   client.nat.add_forward(
+      #     index: 2,
+      #     protocol: 'udp',
+      #     port: 27015,
+      #     end_port: 27030,
+      #     to_host: '192.168.1.50',
+      #     to_port: 27015,
+      #     description: 'Game Server'
+      #   )
+      #
+      def add_forward(index:, protocol:, port:, to_host:, to_port:, interface: 'ISP',
+                      description: nil, end_port: nil, enabled: true)
+        params = {
+          'index' => index,
+          'protocol' => protocol,
+          'interface' => interface,
+          'port' => port,
+          'to-host' => to_host,
+          'to-port' => to_port,
+          'enabled' => enabled
+        }
+        params['description'] = description if description
+        params['end-port'] = end_port if end_port
+
+        post('/rci/ip/nat', params)
+      end
+
+      # Delete a port forwarding rule.
+      #
+      # == Keenetic API Request
+      #   POST /rci/ip/nat
+      #   Body: { index, no: true }
+      #
+      # @param index [Integer] Rule index to delete
+      # @return [Hash, Array, nil] API response
+      #
+      # @example
+      #   client.nat.delete_forward(index: 1)
+      #
+      def delete_forward(index:)
+        post('/rci/ip/nat', { 'index' => index, 'no' => true })
+      end
+
+      # Get all UPnP port mappings.
+      #
+      # UPnP mappings are automatically created by devices on the network.
+      # These are read-only and managed by the devices themselves.
+      #
+      # == Keenetic API Request
+      #   GET /rci/show/upnp/redirect
+      #
+      # == Response Fields
+      #   - protocol: "tcp" or "udp"
+      #   - interface: WAN interface
+      #   - port: External port
+      #   - to_host: Internal host IP
+      #   - to_port: Internal port
+      #   - description: Mapping description (from device)
+      #
+      # @return [Array<Hash>] List of normalized UPnP mappings
+      # @example
+      #   mappings = client.nat.upnp_mappings
+      #   # => [{ protocol: "tcp", port: 51234, to_host: "192.168.1.50", ... }]
+      #
+      def upnp_mappings
+        response = get('/rci/show/upnp/redirect')
+        normalize_upnp_mappings(response)
+      end
+
+      private
+
+      def normalize_upnp_mappings(response)
+        return [] unless response.is_a?(Array)
+
+        response.map { |mapping| normalize_upnp_mapping(mapping) }.compact
+      end
+
+      def normalize_upnp_mapping(data)
+        return nil unless data.is_a?(Hash)
+
+        {
+          protocol: data['protocol'],
+          interface: data['interface'],
+          port: data['port'],
+          to_host: data['to-host'],
+          to_port: data['to-port'],
+          description: data['description']
+        }
+      end
+
+      def normalize_rules(response)
+        return [] unless response.is_a?(Array)
+
+        response.map { |rule| normalize_rule(rule) }.compact
+      end
+
+      def normalize_rule(data)
+        return nil unless data.is_a?(Hash)
+
+        {
+          index: data['index'],
+          description: data['description'],
+          protocol: data['protocol'],
+          interface: data['interface'],
+          port: data['port'],
+          end_port: data['end-port'],
+          to_host: data['to-host'],
+          to_port: data['to-port'],
+          enabled: normalize_boolean(data['enabled'])
+        }
+      end
+    end
+  end
+end

data/lib/keenetic/resources/qos.rb

@@ -0,0 +1,89 @@
+module Keenetic
+  module Resources
+    # QoS resource for Quality of Service and traffic control.
+    #
+    # == API Endpoints Used
+    #
+    # === Traffic Shaper Status
+    #   GET /rci/show/ip/traffic-control
+    #
+    # === IntelliQoS Settings
+    #   GET /rci/show/ip/qos
+    #
+    # === Traffic Statistics by Host
+    #   GET /rci/show/ip/hotspot/summary
+    #
+    class Qos < Base
+      # Get traffic shaper status.
+      #
+      # @return [Hash] Traffic shaper configuration and status
+      # @example
+      #   shaper = client.qos.traffic_shaper
+      #
+      def traffic_shaper
+        response = get('/rci/show/ip/traffic-control')
+        normalize_response(response)
+      end
+
+      # Alias for traffic_shaper
+      alias shaper traffic_shaper
+
+      # Get IntelliQoS settings.
+      #
+      # @return [Hash] IntelliQoS configuration
+      # @example
+      #   qos = client.qos.intelliqos
+      #
+      def intelliqos
+        response = get('/rci/show/ip/qos')
+        normalize_response(response)
+      end
+
+      # Alias for intelliqos
+      alias settings intelliqos
+
+      # Get traffic statistics by host.
+      #
+      # @return [Array<Hash>] Traffic statistics per host
+      # @example
+      #   stats = client.qos.traffic_stats
+      #
+      def traffic_stats
+        response = get('/rci/show/ip/hotspot/summary')
+        normalize_stats(response)
+      end
+
+      # Alias for traffic_stats
+      alias host_stats traffic_stats
+
+      private
+
+      def normalize_response(response)
+        return {} unless response.is_a?(Hash)
+
+        deep_normalize_keys(response)
+      end
+
+      def normalize_stats(response)
+        stats_data = case response
+                     when Array
+                       response
+                     when Hash
+                       response['host'] || response['hosts'] || response['stat'] || []
+                     else
+                       []
+                     end
+
+        return [] unless stats_data.is_a?(Array)
+
+        stats_data.map { |stat| normalize_stat(stat) }.compact
+      end
+
+      def normalize_stat(data)
+        return nil unless data.is_a?(Hash)
+
+        deep_normalize_keys(data)
+      end
+    end
+  end
+end

data/lib/keenetic/resources/schedule.rb

@@ -0,0 +1,87 @@
+module Keenetic
+  module Resources
+    # Schedule resource for managing access control schedules.
+    #
+    # == API Endpoints Used
+    #
+    # === List Schedules
+    #   GET /rci/show/schedule
+    #
+    # === Create Schedule
+    #   POST /rci/schedule
+    #
+    # === Delete Schedule
+    #   POST /rci/schedule with { "name": "...", "no": true }
+    #
+    class Schedule < Base
+      # List all schedules.
+      #
+      # @return [Array<Hash>] List of schedules
+      # @example
+      #   schedules = client.schedule.all
+      #
+      def all
+        response = get('/rci/show/schedule')
+        normalize_schedules(response)
+      end
+
+      # Find a schedule by name.
+      #
+      # @param name [String] Schedule name
+      # @return [Hash, nil] Schedule data or nil
+      #
+      def find(name)
+        all.find { |s| s[:name] == name }
+      end
+
+      # Create a new schedule.
+      #
+      # @param name [String] Schedule name
+      # @param entries [Array<Hash>] Schedule entries with days, start, end, action
+      # @return [Hash, nil] API response
+      # @example
+      #   client.schedule.create(
+      #     name: 'kids_bedtime',
+      #     entries: [
+      #       { days: 'mon,tue,wed,thu,fri', start: '22:00', end: '07:00', action: 'deny' }
+      #     ]
+      #   )
+      #
+      def create(name:, entries:)
+        post('/rci/schedule', { 'name' => name, 'entries' => entries })
+      end
+
+      # Delete a schedule.
+      #
+      # @param name [String] Schedule name
+      # @return [Hash, nil] API response
+      #
+      def delete(name:)
+        post('/rci/schedule', { 'name' => name, 'no' => true })
+      end
+
+      private
+
+      def normalize_schedules(response)
+        schedules_data = case response
+                         when Array
+                           response
+                         when Hash
+                           response['schedule'] || response['schedules'] || []
+                         else
+                           []
+                         end
+
+        return [] unless schedules_data.is_a?(Array)
+
+        schedules_data.map { |schedule| normalize_schedule(schedule) }.compact
+      end
+
+      def normalize_schedule(data)
+        return nil unless data.is_a?(Hash)
+
+        deep_normalize_keys(data)
+      end
+    end
+  end
+end