novacloud_client 0.1.0

data/lib/novacloud_client/objects/screen.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module NovacloudClient
+  module Objects
+    # Represents a screen/device entry from VNNOXCare APIs.
+    class Screen < Base
+      attr_accessor :sid, :name, :mac, :sn, :address, :longitude, :latitude,
+                    :status, :camera, :brightness, :env_brightness
+
+      def online?
+        status.to_i == 1
+      end
+
+      def camera_enabled?
+        camera.to_i == 1
+      end
+    end
+  end
+end

data/lib/novacloud_client/objects/screen_detail.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module NovacloudClient
+  module Objects
+    # Represents detailed telemetry for a screen, including nested hardware info.
+    class ScreenDetail < Base
+      attr_accessor :identifier, :input_source, :mac, :master_control, :module,
+                    :monitor_card, :receiving_card, :screen, :sid, :smart_module, :sn
+
+      NESTED_HASH_FIELDS = %i[input_source master_control module monitor_card receiving_card screen smart_module].freeze
+
+      def initialize(attributes = {})
+        super
+        ensure_nested_hashes!
+      end
+
+      private
+
+      def ensure_nested_hashes!
+        NESTED_HASH_FIELDS.each do |field|
+          value = public_send(field)
+          public_send("#{field}=", value || {})
+        end
+      end
+    end
+  end
+end

data/lib/novacloud_client/objects/screen_monitor.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module NovacloudClient
+  module Objects
+    # Represents high-level monitoring metrics for a screen device.
+    class ScreenMonitor < Base
+      attr_accessor :display_device, :brightness, :env_brightness, :height, :width, :sn
+    end
+  end
+end

data/lib/novacloud_client/objects/solutions/offline_export_result.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module NovacloudClient
+  module Objects
+    module Solutions
+      # Represents the payload returned from the offline export endpoint.
+      class OfflineExportResult < Base
+        attr_reader :display_solutions, :play_relations, :play_solutions,
+                    :playlists, :schedule_constraints, :plan_json
+
+        def display_solutions=(value)
+          @display_solutions = build_artifact(value)
+        end
+
+        def play_relations=(value)
+          @play_relations = build_artifact(value)
+        end
+
+        def play_solutions=(value)
+          @play_solutions = build_artifact(value)
+        end
+
+        def playlists=(value)
+          @playlists = build_artifact(value)
+        end
+
+        def schedule_constraints=(value)
+          @schedule_constraints = build_artifact(value)
+        end
+
+        def plan_json=(value)
+          @plan_json = build_artifact(value)
+        end
+
+        private
+
+        def build_artifact(value)
+          return nil if value.nil?
+
+          if value.is_a?(Array)
+            value.map { |artifact| Artifact.new(artifact) }
+          else
+            Artifact.new(value)
+          end
+        end
+
+        # Represents a downloadable artifact (JSON, playlist, etc.) returned by the export.
+        class Artifact < Base
+          attr_accessor :md5, :file_name, :url, :program_name
+
+          attr_writer :support_md5_checkout
+
+          def support_md5_checkout
+            return nil if @support_md5_checkout.nil?
+
+            !!@support_md5_checkout
+          end
+
+          def support_md5_checkout?
+            support_md5_checkout
+          end
+
+          # Legacy camelCase accessors for backward compatibility with existing clients.
+          # Legacy camelCase accessors for backward compatibility with existing clients.
+          # rubocop:disable Naming/PredicatePrefix
+          def is_support_md5_checkout?
+            support_md5_checkout?
+          end
+
+          def is_support_md5_checkout=(value)
+            self.support_md5_checkout = value
+          end
+          # rubocop:enable Naming/PredicatePrefix
+        end
+      end
+    end
+  end
+end

data/lib/novacloud_client/objects/solutions/over_spec_detection_result.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module NovacloudClient
+  module Objects
+    module Solutions
+      # Represents the payload returned when checking program over-specification.
+      class OverSpecDetectionResult < Base
+        attr_accessor :logid, :status
+        attr_reader :items
+
+        def initialize(attributes = {})
+          @items = []
+          super
+        end
+
+        def data=(value)
+          @items = Array(value).map { |entry| Item.new(entry) }
+        end
+
+        alias data items
+
+        # Entry describing over-specification findings for a specific set of players.
+        class Item < Base
+          attr_accessor :over_spec_type
+          attr_reader :over_spec, :player_ids
+
+          def initialize(attributes = {})
+            @details = []
+            super
+          end
+
+          def over_spec=(value)
+            @over_spec = !!value
+          end
+
+          def over_spec?
+            over_spec
+          end
+
+          def player_ids=(value)
+            @player_ids = Array(value)
+          end
+
+          def over_spec_detail=(value)
+            @details = Array(value).map { |detail| Detail.new(detail) }
+          end
+
+          def details
+            @details ||= []
+          end
+
+          # Detail record for a widget that exceeds specifications.
+          class Detail < Base
+            attr_accessor :page_id, :widget_id
+            attr_reader :over_spec_error_code, :recommendation
+
+            def over_spec_error_code=(value)
+              @over_spec_error_code = Array(value)
+            end
+
+            def over_spec_error_codes
+              @over_spec_error_code
+            end
+
+            def recommend=(value)
+              @recommendation = value ? Recommendation.new(value) : nil
+            end
+
+            # Suggested adjustments for bringing a widget within spec.
+            class Recommendation < Base
+              attr_accessor :width, :height, :postfix, :fps, :byte_rate, :codec
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/novacloud_client/objects/solutions/publish_result.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module NovacloudClient
+  module Objects
+    module Solutions
+      # Represents the publish result structure returned by solution endpoints.
+      class PublishResult < Base
+        def success=(value)
+          @successful = Array(value).compact
+        end
+
+        def fail=(value)
+          @failed = Array(value).compact
+        end
+
+        def all_successful?
+          failed.empty?
+        end
+
+        def failed
+          @failed ||= []
+        end
+
+        def successful
+          @successful ||= []
+        end
+      end
+    end
+  end
+end

data/lib/novacloud_client/resources/base.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module NovacloudClient
+  module Resources
+    # Shared helpers for resource classes built on top of the client.
+    class Base
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      def get(endpoint, params: {})
+        client.request(http_method: :get, endpoint: endpoint, params: params)
+      end
+
+      def post(endpoint, params: {})
+        client.request(http_method: :post, endpoint: endpoint, params: params)
+      end
+
+      def validate_player_ids!(ids, max: 100)
+        raise ArgumentError, "player_ids cannot be empty" if ids.nil? || ids.empty?
+        raise ArgumentError, "maximum #{max} player IDs allowed" if ids.size > max
+      end
+    end
+  end
+end

data/lib/novacloud_client/resources/concerns/payload_serializer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module NovacloudClient
+  module Resources
+    module Concerns
+      # Provides camelCase serialization helpers for API payloads.
+      module PayloadSerializer
+        private
+
+        def serialize_component(component)
+          case component
+          when nil
+            nil
+          when Hash
+            component.each_with_object({}) do |(key, value), result|
+              result[camelize_key(key)] = serialize_component(value)
+            end
+          when Array
+            component.map { |item| serialize_component(item) }
+          else
+            component.respond_to?(:to_h) ? serialize_component(component.to_h) : component
+          end
+        end
+
+        def camelize_key(key)
+          return key unless key.is_a?(String) || key.is_a?(Symbol)
+
+          string = key.to_s
+          normalized = string
+                       .gsub(/([a-z\d])([A-Z])/, "\\1_\\2")
+                       .tr("-", "_")
+                       .downcase
+
+          parts = normalized.split("_")
+          camelized = parts.map.with_index do |segment, index|
+            next segment if index.zero?
+
+            segment.capitalize
+          end
+
+          camelized.join
+        end
+      end
+    end
+  end
+end

data/lib/novacloud_client/resources/control.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../objects/control_result"
+require_relative "../objects/queued_request"
+
+module NovacloudClient
+  module Resources
+    # Resource wrapper for control commands.
+    #
+    # @example Set player brightness
+    #   client.control.brightness(
+    #     player_ids: ["player-1"],
+    #     brightness: 80,
+    #     notice_url: "https://example.com/callback"
+    #   )
+    #
+    # @example Check a queued request
+    #   request = client.control.reboot(player_ids: ["player-1"], notice_url: callback)
+    #   client.control.request_result(request_id: request.request_id)
+    class Control < Base
+      MAX_BATCH = 100
+
+      # Adjust brightness asynchronously for a batch of players.
+      #
+      # @param player_ids [Array<String>] NovaCloud player identifiers (max #{MAX_BATCH})
+      # @param brightness [Integer] percentage value between 0 and 100
+      # @param notice_url [String] HTTPS callback endpoint for async results
+      # @return [NovacloudClient::Objects::QueuedRequest]
+      # @raise [ArgumentError] when validation fails
+      def brightness(player_ids:, brightness:, notice_url:)
+        validate_percentage!(brightness, "brightness")
+        enqueue_control(
+          endpoint: "/v2/player/real-time-control/brightness",
+          player_ids: player_ids,
+          notice_url: notice_url,
+          extra_payload: { brightness: brightness }
+        )
+      end
+
+      # Adjust volume asynchronously for a batch of players.
+      #
+      # @param player_ids [Array<String>] NovaCloud player identifiers (max #{MAX_BATCH})
+      # @param volume [Integer] percentage value between 0 and 100
+      # @param notice_url [String] HTTPS callback endpoint for async results
+      # @return [NovacloudClient::Objects::QueuedRequest]
+      # @raise [ArgumentError] when validation fails
+      def volume(player_ids:, volume:, notice_url:)
+        validate_percentage!(volume, "volume")
+        enqueue_control(
+          endpoint: "/v2/player/real-time-control/volume",
+          player_ids: player_ids,
+          notice_url: notice_url,
+          extra_payload: { volume: volume }
+        )
+      end
+
+      # Switch the video input source (e.g., HDMI1) for the selected players.
+      #
+      # @param player_ids [Array<String>] NovaCloud player identifiers (max #{MAX_BATCH})
+      # @param source [String] identifier for the input source defined by NovaCloud (e.g., "HDMI1")
+      # @param notice_url [String] HTTPS callback endpoint for async results
+      # @return [NovacloudClient::Objects::QueuedRequest]
+      # @raise [ArgumentError] when validation fails
+      def video_source(player_ids:, source:, notice_url:)
+        validate_presence!(source, "source")
+        enqueue_control(
+          endpoint: "/v2/player/real-time-control/video-source",
+          player_ids: player_ids,
+          notice_url: notice_url,
+          extra_payload: { videoSource: source }
+        )
+      end
+
+      # Toggle screen power state for the selected players.
+      #
+      # @param player_ids [Array<String>] NovaCloud player identifiers (max #{MAX_BATCH})
+      # @param state [Symbol, String, Integer, TrueClass, FalseClass] desired power state
+      #   (:on, :off, true, false, 1, or 0)
+      # @param notice_url [String] HTTPS callback endpoint for async results
+      # @return [NovacloudClient::Objects::QueuedRequest]
+      # @raise [ArgumentError] when validation fails
+      def screen_power(player_ids:, state:, notice_url:)
+        payload = { option: normalize_power_state(state) }
+        enqueue_control(
+          endpoint: "/v2/player/real-time-control/power",
+          player_ids: player_ids,
+          notice_url: notice_url,
+          extra_payload: payload
+        )
+      end
+
+      # Request a black screen/normal screen toggle for the selected players.
+      #
+      # @param player_ids [Array<String>] NovaCloud player identifiers (max #{MAX_BATCH})
+      # @param status [String, Symbol] desired screen mode (:open, :close, "OPEN", "CLOSE")
+      # @param notice_url [String] HTTPS callback endpoint for async results
+      # @return [NovacloudClient::Objects::QueuedRequest]
+      # @raise [ArgumentError] when validation fails
+      def screen_status(player_ids:, status:, notice_url:)
+        payload = { status: normalize_screen_status(status) }
+        enqueue_control(
+          endpoint: "/v2/player/real-time-control/screen-status",
+          player_ids: player_ids,
+          notice_url: notice_url,
+          extra_payload: payload
+        )
+      end
+
+      # Trigger screenshots for the selected players.
+      #
+      # @param player_ids [Array<String>] NovaCloud player identifiers (max #{MAX_BATCH})
+      # @param notice_url [String] HTTPS callback endpoint receiving screenshot info
+      # @return [NovacloudClient::Objects::QueuedRequest]
+      # @raise [ArgumentError] when validation fails
+      def screenshot(player_ids:, notice_url:)
+        enqueue_control(
+          endpoint: "/v2/player/real-time-control/screen-capture",
+          player_ids: player_ids,
+          notice_url: notice_url
+        )
+      end
+
+      # Reboot one or more players asynchronously.
+      #
+      # @param player_ids [Array<String>] NovaCloud player identifiers (max #{MAX_BATCH})
+      # @param notice_url [String] HTTPS callback endpoint for async results
+      # @return [NovacloudClient::Objects::QueuedRequest]
+      # @raise [ArgumentError] when validation fails
+      def reboot(player_ids:, notice_url:)
+        enqueue_control(
+          endpoint: "/v2/player/real-time-control/reboot",
+          player_ids: player_ids,
+          notice_url: notice_url
+        )
+      end
+
+      # Configure NTP time synchronization for the selected players.
+      #
+      # @param player_ids [Array<String>] NovaCloud player identifiers (max #{MAX_BATCH})
+      # @param server [String] NTP server hostname
+      # @param enable [Boolean] flag indicating whether to enable synchronization
+      # @return [NovacloudClient::Objects::ControlResult]
+      def ntp_sync(player_ids:, server:, enable:)
+        validate_player_ids!(player_ids, max: MAX_BATCH)
+        validate_presence!(server, "server")
+        validate_boolean!(enable, "enable")
+
+        payload = {
+          playerIds: player_ids,
+          server: server,
+          enable: !enable.nil?
+        }
+
+        response = post("/v2/player/real-time-control/ntp", params: payload)
+        Objects::ControlResult.new(response)
+      end
+
+      # Toggle synchronous playback mode in real-time.
+      #
+      # @param player_ids [Array<String>] NovaCloud player identifiers (max #{MAX_BATCH})
+      # @param option [Integer, Symbol, String, TrueClass, FalseClass] desired synchronous state
+      # @return [NovacloudClient::Objects::ControlResult]
+      def synchronous_playback(player_ids:, option:)
+        validate_player_ids!(player_ids, max: MAX_BATCH)
+
+        payload = {
+          playerIds: player_ids,
+          option: normalize_sync_option(option)
+        }
+
+        response = post("/v2/player/real-time-control/simulcast", params: payload)
+        Objects::ControlResult.new(response)
+      end
+
+      # Fetch the aggregated result of a previously queued control request.
+      #
+      # @param request_id [String] identifier returned by the queueing endpoints
+      # @return [NovacloudClient::Objects::ControlResult]
+      # @raise [ArgumentError] when the request ID is blank
+      def request_result(request_id:)
+        raise ArgumentError, "request_id is required" if request_id.to_s.strip.empty?
+
+        response = get("/v2/player/control/request-result", params: { requestId: request_id })
+        Objects::ControlResult.new(response)
+      end
+
+      private
+
+      def validate_percentage!(value, field)
+        return if value.is_a?(Integer) && value.between?(0, 100)
+
+        raise ArgumentError, "#{field} must be an integer between 0 and 100"
+      end
+
+      def validate_notice_url!(notice_url)
+        raise ArgumentError, "notice_url is required" if notice_url.to_s.strip.empty?
+      end
+
+      def validate_presence!(value, field)
+        raise ArgumentError, "#{field} is required" if value.to_s.strip.empty?
+      end
+
+      def validate_boolean!(value, field)
+        return if [true, false].include?(value)
+
+        raise ArgumentError, "#{field} must be true or false"
+      end
+
+      def enqueue_control(endpoint:, player_ids:, notice_url:, extra_payload: {})
+        validate_player_ids!(player_ids, max: MAX_BATCH)
+        validate_notice_url!(notice_url)
+
+        payload = { playerIds: player_ids }
+        payload.merge!(extra_payload)
+        payload[:noticeUrl] = notice_url
+
+        response = post(endpoint, params: payload)
+        Objects::QueuedRequest.new(response)
+      end
+
+      def normalize_power_state(state)
+        case state
+        when true, :on, "on", "ON", 1 then 1
+        when false, :off, "off", "OFF", 0 then 0
+        else
+          raise ArgumentError, "state must be one of :on, :off, true, false, or 0/1"
+        end
+      end
+
+      def normalize_screen_status(status)
+        case status
+        when :open, "open", "OPEN" then "OPEN"
+        when :close, "close", "CLOSE", :closed then "CLOSE"
+        else
+          raise ArgumentError, "status must be OPEN or CLOSE"
+        end
+      end
+
+      def normalize_sync_option(option)
+        case option
+        when true, :on, "on", "ON", 1 then 1
+        when false, :off, "off", "OFF", 0 then 0
+        else
+          raise ArgumentError, "option must be one of :on, :off, true, false, or 0/1"
+        end
+      end
+    end
+  end
+end

data/lib/novacloud_client/resources/logs.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../objects/control_log_entry"
+
+module NovacloudClient
+  module Resources
+    # Resource wrapper for log-related endpoints.
+    class Logs < Base
+      # Retrieve remote control execution history for a player.
+      #
+      # @param player_id [String] NovaCloud player identifier
+      # @param start [Integer] pagination offset (defaults to 0)
+      # @param count [Integer] number of records to request (defaults to 20)
+      # @param task_type [Integer, nil] optional numeric filter defined by NovaCloud
+      # @return [Array<NovacloudClient::Objects::ControlLogEntry>]
+      def control_history(player_id:, start: 0, count: 20, task_type: nil)
+        validate_presence!(player_id, "player_id")
+
+        params = {
+          "playerId" => player_id,
+          "start" => start.to_s,
+          "count" => count.to_s
+        }
+        params["taskType"] = task_type.to_s if task_type
+
+        response = get("/v2/logs/remote-control", params: params)
+        rows = response.fetch("rows", [])
+        rows.map { |attrs| Objects::ControlLogEntry.new(attrs) }
+      end
+
+      private
+
+      def validate_presence!(value, field)
+        raise ArgumentError, "#{field} is required" if value.to_s.strip.empty?
+      end
+    end
+  end
+end