novacloud_client 0.1.0

data/lib/novacloud_client/resources/players.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../objects/player"
+require_relative "../objects/player_status"
+require_relative "../objects/queued_request"
+
+module NovacloudClient
+  module Resources
+    # Resource wrapper for player-related endpoints.
+    #
+    # @example Fetch the first page of configured players
+    #   client.players.list(count: 50)
+    #
+    # @example Fetch online status by player IDs
+    #   client.players.statuses(player_ids: ["player-1", "player-2"])
+    #
+    # @example Request running status callbacks
+    #   client.players.running_status(
+    #     player_ids: ["player-1"],
+    #     commands: ["screenshot"],
+    #     notice_url: "https://example.com/callback"
+    #   )
+    class Players < Base
+      MAX_BATCH = 100
+      CONFIG_STATUS_COMMANDS = %w[
+        volumeValue
+        brightnessValue
+        videoSourceValue
+        timeValue
+        screenPowerStatus
+        syncPlayStatus
+        powerStatus
+      ].freeze
+
+      # Retrieve players with optional pagination and fuzzy name filtering.
+      #
+      # @param start [Integer] pagination offset provided by NovaCloud (defaults to 0)
+      # @param count [Integer] number of records to request (NovaCloud default is 20)
+      # @param name [String, nil] optional fuzzy match on the player name
+      # @return [Array<NovacloudClient::Objects::Player>]
+      def list(start: 0, count: 20, name: nil)
+        params = { start: start, count: count }
+        params[:name] = name if name
+
+        response = get("/v2/player/list", params: params)
+        rows = response.fetch("rows", [])
+        rows.map { |attrs| Objects::Player.new(attrs) }
+      end
+
+      # Retrieve current online status for a set of players.
+      #
+      # @param player_ids [Array<String>, nil] NovaCloud player identifiers (max #{MAX_BATCH})
+      # @param player_sns [Array<String>, nil] player serial numbers (max #{MAX_BATCH})
+      # @return [Array<NovacloudClient::Objects::PlayerStatus>]
+      # @raise [ArgumentError] when no identifiers are provided
+      def statuses(player_ids: nil, player_sns: nil)
+        payload = build_status_payload(player_ids: player_ids, player_sns: player_sns)
+        response = post("/v2/player/current/online-status", params: payload)
+        Array(response).map { |attrs| Objects::PlayerStatus.new(attrs) }
+      end
+
+      # Enqueue a running-status command and receive a queued request reference.
+      #
+      # @param player_ids [Array<String>] NovaCloud player identifiers (max #{MAX_BATCH})
+      # @param commands [Array<String>] running status command names defined by NovaCloud
+      # @param notice_url [String] HTTPS callback endpoint for async results
+      # @return [NovacloudClient::Objects::QueuedRequest]
+      # @raise [ArgumentError] when validation fails
+      def running_status(player_ids:, commands:, notice_url:)
+        validate_player_ids!(player_ids, max: MAX_BATCH)
+        raise ArgumentError, "commands cannot be empty" if commands.nil? || commands.empty?
+        raise ArgumentError, "notice_url is required" if notice_url.to_s.strip.empty?
+
+        payload = {
+          playerIds: player_ids,
+          commands: commands,
+          noticeUrl: notice_url
+        }
+
+        response = post("/v2/player/current/running-status", params: payload)
+        Objects::QueuedRequest.new(response)
+      end
+
+      # Convenience wrapper around `running_status` for configuration polling.
+      # Uses NovaCloud's recommended command set by default.
+      def config_status(player_ids:, notice_url:, commands: CONFIG_STATUS_COMMANDS)
+        running_status(player_ids: player_ids, commands: commands, notice_url: notice_url)
+      end
+
+      # Delegate to the control resource for NTP time synchronization settings.
+      def ntp_sync(player_ids:, server:, enable:)
+        client.control.ntp_sync(player_ids: player_ids, server: server, enable: enable)
+      end
+
+      # Delegate to the control resource for synchronous playback toggles.
+      def synchronous_playback(player_ids:, option:)
+        client.control.synchronous_playback(player_ids: player_ids, option: option)
+      end
+
+      private
+
+      def build_status_payload(player_ids:, player_sns:)
+        payload = {}
+        if player_ids
+          validate_player_ids!(player_ids, max: MAX_BATCH)
+          payload[:playerIds] = player_ids
+        end
+        if player_sns
+          validate_player_ids!(player_sns, max: MAX_BATCH)
+          payload[:playerSns] = player_sns
+        end
+
+        raise ArgumentError, "provide player_ids or player_sns" if payload.empty?
+
+        payload
+      end
+    end
+  end
+end

data/lib/novacloud_client/resources/scheduled_control.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../objects/control_result"
+require_relative "../support/key_transform"
+
+module NovacloudClient
+  module Resources
+    # Resource wrapper for scheduled control operations.
+    class ScheduledControl < Base
+      MAX_BATCH = 100
+
+      # Configure scheduled screen status plans for players.
+      def screen_status(player_ids:, schedules:)
+        normalized = normalize_schedules(schedules) do |base, original|
+          wk = fetch_optional(original, :week_days, "week_days", :weekDays, "weekDays")
+          base[:week_days] = Array(wk || [])
+
+          base[:exec_time] = fetch_required(original, :exec_time, "exec_time", :execTime, "execTime")
+
+          status = fetch_required(original, :status, "status")
+          base[:status] = normalize_screen_status(status)
+          base
+        end
+
+        schedule_request(
+          endpoint: "/v2/player/scheduled-control/screen-status",
+          player_ids: player_ids,
+          schedules: normalized
+        )
+      end
+
+      # Configure scheduled reboots for players.
+      def reboot(player_ids:, schedules:)
+        normalized = normalize_schedules(schedules) do |base, original|
+          base[:exec_time] = fetch_required(original, :exec_time, "exec_time", :execTime, "execTime")
+          base
+        end
+
+        schedule_request(
+          endpoint: "/v2/player/scheduled-control/reboot",
+          player_ids: player_ids,
+          schedules: normalized
+        )
+      end
+
+      # Configure scheduled volume adjustments for players.
+      def volume(player_ids:, schedules:)
+        normalized = normalize_schedules(schedules) do |base, original|
+          base[:exec_time] = fetch_required(original, :exec_time, "exec_time", :execTime, "execTime")
+
+          value = fetch_required(original, :value, "value")
+          validate_percentage!(value, "value")
+          base[:value] = value.to_i
+
+          wk = fetch_optional(original, :week_days, "week_days", :weekDays, "weekDays")
+          base[:week_days] = Array(wk || [])
+          base
+        end
+
+        schedule_request(
+          endpoint: "/v2/player/scheduled-control/volume",
+          player_ids: player_ids,
+          schedules: normalized
+        )
+      end
+
+      # Configure scheduled brightness adjustments for players.
+      # @param auto_profile [Hash, nil] optional auto brightness profile
+      def brightness(player_ids:, schedules:, auto_profile: nil)
+        normalized = normalize_schedules(schedules) do |base, original|
+          base[:exec_time] = fetch_required(original, :exec_time, "exec_time", :execTime, "execTime")
+
+          type = fetch_required(original, :type, "type")
+          base[:type] = type.to_i
+
+          value = fetch_optional(original, :value, "value")
+          base[:value] = value.to_i if value
+          base
+        end
+
+        extra_payload = {}
+        extra_payload[:auto_profile] = auto_profile if auto_profile
+
+        schedule_request(
+          endpoint: "/v2/player/scheduled-control/brightness",
+          player_ids: player_ids,
+          schedules: normalized,
+          extra_payload: extra_payload
+        )
+      end
+
+      # Configure scheduled video source switching for players.
+      def video_source(player_ids:, schedules:)
+        normalized = normalize_schedules(schedules) do |base, original|
+          base[:exec_time] = fetch_required(original, :exec_time, "exec_time", :execTime, "execTime")
+
+          source = fetch_required(original, :source, "source")
+          base[:source] = source
+
+          wk = fetch_optional(original, :week_days, "week_days", :weekDays, "weekDays")
+          base[:week_days] = Array(wk) unless wk.nil?
+
+          base
+        end
+
+        schedule_request(
+          endpoint: "/v2/player/scheduled-control/video-source",
+          player_ids: player_ids,
+          schedules: normalized
+        )
+      end
+
+      private
+
+      def normalize_schedules(schedules)
+        raise ArgumentError, "schedules must be provided" if schedules.nil?
+
+        array = schedules.is_a?(Array) ? schedules : [schedules]
+        raise ArgumentError, "schedules cannot be empty" if array.empty?
+
+        array.map do |entry|
+          base, original = build_base_schedule(entry)
+          block_given? ? yield(base, original) : base
+        end
+      end
+
+      def build_base_schedule(entry)
+        hash = entry.respond_to?(:to_h) ? entry.to_h : entry
+        raise ArgumentError, "schedule entries must be hash-like" unless hash.is_a?(Hash)
+
+        # Only set date fields; callers append exec_time, values, and week_days
+        # for each endpoint-specific payload requirement.
+        base = {
+          start_date: fetch_required(hash, :start_date, "start_date", :startDate, "startDate"),
+          end_date: fetch_required(hash, :end_date, "end_date", :endDate, "endDate")
+        }
+
+        [base, hash]
+      end
+
+      def schedule_request(endpoint:, player_ids:, schedules:, extra_payload: {})
+        validate_player_ids!(player_ids, max: MAX_BATCH)
+
+        payload = {
+          player_ids: player_ids,
+          schedules: schedules
+        }
+        payload.merge!(extra_payload) if extra_payload && !extra_payload.empty?
+        cleaned = cleanup_schedule_payload(endpoint, payload)
+
+        response = post(endpoint, params: Support::KeyTransform.camelize_component(cleaned))
+        Objects::ControlResult.new(response)
+      end
+
+      # Remove empty weekDays for endpoints that expect them omitted in tests/docs
+      def cleanup_schedule_payload(endpoint, payload)
+        return payload unless omit_empty_week_days?(endpoint)
+
+        cleaned = Marshal.load(Marshal.dump(payload))
+        Array(cleaned[:schedules]).each do |schedule|
+          next unless schedule.key?(:week_days)
+
+          schedule.delete(:week_days) if blank_week_days?(schedule[:week_days])
+        end
+
+        cleaned
+      end
+
+      def omit_empty_week_days?(endpoint)
+        [
+          "/v2/player/scheduled-control/brightness",
+          "/v2/player/scheduled-control/video-source"
+        ].include?(endpoint.to_s)
+      end
+
+      def blank_week_days?(values)
+        return true if values.nil?
+        return values.empty? if values.respond_to?(:empty?)
+
+        false
+      end
+
+      def fetch_required(hash, *keys)
+        value = fetch_optional(hash, *keys)
+        raise ArgumentError, "#{keys.first} is required" if value.nil? || value.to_s.strip.empty?
+
+        value
+      end
+
+      def fetch_optional(hash, *keys, default: nil)
+        keys.each do |key|
+          string_key = key.to_s
+          return hash[key] if hash.key?(key)
+          return hash[string_key] if hash.key?(string_key)
+
+          symbol_key = string_key.to_sym
+          return hash[symbol_key] if hash.key?(symbol_key)
+        end
+
+        default
+      end
+
+      def validate_percentage!(value, field)
+        int_value = value.to_i
+        return if int_value.between?(0, 100)
+
+        raise ArgumentError, "#{field} must be between 0 and 100"
+      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
+    end
+  end
+end

data/lib/novacloud_client/resources/screens.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../objects/screen"
+require_relative "../objects/screen_monitor"
+require_relative "../objects/screen_detail"
+
+module NovacloudClient
+  module Resources
+    # Resource wrapper around VNNOXCare screen inventory endpoints.
+    class Screens < Base
+      # Retrieve paginated list of screens and monitoring metadata.
+      #
+      # @param start [Integer] pagination offset provided by VNNOXCare (defaults to 0)
+      # @param count [Integer] number of records to request (defaults to 20)
+      # @param status [Integer, nil] optional status filter defined by VNNOXCare (e.g., 1 for online)
+      # @return [Array<NovacloudClient::Objects::Screen>]
+      def list(start: 0, count: 20, status: nil)
+        params = { start: start, count: count }
+        params[:status] = status if status
+
+        response = get("/v2/device-status-monitor/screen/list", params: params)
+        items = response.fetch("items", [])
+        items.map { |attrs| Objects::Screen.new(attrs) }
+      end
+
+      # Retrieve detailed monitoring metrics for a single screen by serial number.
+      #
+      # @param sn [String] screen serial number registered in VNNOXCare
+      # @return [NovacloudClient::Objects::ScreenMonitor]
+      # @raise [ArgumentError] when serial number is blank
+      def monitor(serial_number: nil, **kwargs)
+        serial = serial_number || kwargs[:sn]
+        validate_presence!(serial, "serial_number")
+
+        response = get("/v2/device-status-monitor/screen/monitor/#{serial}")
+        Objects::ScreenMonitor.new(response)
+      end
+
+      # Retrieve deep detail payloads for up to 10 screens at once.
+      #
+      # @param sn_list [Array<String>] list of screen serial numbers (max 10)
+      # @return [Array<NovacloudClient::Objects::ScreenDetail>]
+      # @raise [ArgumentError] when validation fails
+      def detail(sn_list:)
+        validate_sn_list!(sn_list)
+
+        response = post("/v2/device-status-monitor/all", params: { snList: sn_list })
+        values = response.fetch("value", [])
+        values.map { |attrs| Objects::ScreenDetail.new(attrs) }
+      end
+
+      private
+
+      def validate_sn_list!(sn_list)
+        validate_presence!(sn_list, "sn_list")
+        raise ArgumentError, "sn_list cannot be empty" if sn_list.empty?
+        raise ArgumentError, "maximum 10 screen serial numbers allowed" if sn_list.size > 10
+      end
+
+      def validate_presence!(value, field)
+        raise ArgumentError, "#{field} is required" if value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/novacloud_client/resources/solutions.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../objects/solutions/publish_result"
+require_relative "../objects/solutions/offline_export_result"
+require_relative "../objects/solutions/over_spec_detection_result"
+require_relative "../support/key_transform"
+
+module NovacloudClient
+  module Resources
+    # Resource wrapper for solution publishing workflows.
+    class Solutions < Base
+      # Publish a single-page emergency insertion program.
+      #
+      # @param player_ids [Array<String>] target players
+      # @param attribute [Hash, #to_h] emergency-specific metadata
+      # @param page [Hash, #to_h] definition of the single emergency page
+      # @return [NovacloudClient::Objects::Solutions::PublishResult]
+      def emergency_page(player_ids:, attribute:, page:)
+        validate_player_ids!(player_ids)
+        validate_presence!(attribute, "attribute")
+        validate_presence!(page, "page")
+
+        payload = Support::KeyTransform.camelize_component(
+          playerIds: player_ids,
+          attribute: attribute,
+          page: page
+        )
+
+        response = post("/v2/player/emergency-program/page", params: payload)
+        build_publish_result(response)
+      end
+
+      # Cancel any active emergency program for the provided players.
+      #
+      # @param player_ids [Array<String>]
+      # @return [NovacloudClient::Objects::Solutions::PublishResult]
+      def cancel_emergency(player_ids:)
+        validate_player_ids!(player_ids)
+
+        payload = Support::KeyTransform.camelize_component(playerIds: player_ids)
+        response = post("/v2/player/emergency-program/cancel", params: payload)
+        build_publish_result(response)
+      end
+
+      # Publish a normal (common) solution schedule to the given players.
+      #
+      # @param player_ids [Array<String>] target players
+      # @param pages [Array<Hash, #to_h>] program pages to publish
+      # @param schedule [Hash, #to_h, nil] optional schedule definition
+      # @return [NovacloudClient::Objects::Solutions::PublishResult]
+      def common_solution(player_ids:, pages:, schedule: nil)
+        validate_player_ids!(player_ids)
+        validate_presence!(pages, "pages")
+
+        payload = Support::KeyTransform.camelize_component(
+          playerIds: player_ids,
+          pages: pages
+        )
+        payload[:schedule] = Support::KeyTransform.camelize_component(schedule) if schedule
+
+        response = post("/v2/player/program/normal", params: payload)
+        build_publish_result(response)
+      end
+
+      # Export an offline program bundle without publishing it to devices.
+      #
+      # @param program_type [Integer] NovaCloud program type identifier
+      # @param pages [Array<Hash, #to_h>] program pages to include
+      # @param plan_version [String, nil] optional plan version (defaults to V2 when provided)
+      # @param schedule [Hash, #to_h, nil] optional playback schedule definition
+      # @param options [Hash] additional top-level attributes supported by the API
+      # @return [NovacloudClient::Objects::Solutions::OfflineExportResult]
+      def offline_export(program_type:, pages:, plan_version: nil, schedule: nil, **options)
+        validate_presence!(pages, "pages")
+        raise ArgumentError, "program_type is required" if program_type.nil?
+
+        payload = {
+          program_type: program_type,
+          pages: pages,
+          plan_version: plan_version,
+          schedule: schedule
+        }.merge(options)
+
+        camelized = Support::KeyTransform.camelize_component(compact_hash(payload))
+
+        response = post("/v2/player/program/offline-export", params: camelized)
+        Objects::Solutions::OfflineExportResult.new(response || {})
+      end
+
+      # Enable or disable over-specification detection on the selected players.
+      #
+      # @param player_ids [Array<String>] target players
+      # @param enable [Boolean] whether detection should be enabled
+      # @return [NovacloudClient::Objects::Solutions::PublishResult]
+      def set_over_spec_detection(player_ids:, enable:)
+        validate_player_ids!(player_ids)
+        validate_boolean!(enable, "enable")
+
+        payload = {
+          playerIds: player_ids,
+          enable: enable
+        }
+
+        response = post("/v2/player/immediateControl/over-specification-options", params: payload)
+        build_publish_result(response)
+      end
+
+      # Validate whether a program will exceed the hardware specifications.
+      #
+      # @param player_ids [Array<String>] players against which to test
+      # @param pages [Array<Hash, #to_h>] the program definition to analyse
+      # @return [NovacloudClient::Objects::Solutions::OverSpecDetectionResult]
+      def program_over_spec_detection(player_ids:, pages:)
+        validate_player_ids!(player_ids)
+        validate_presence!(pages, "pages")
+
+        payload = Support::KeyTransform.camelize_component(
+          playerIds: player_ids,
+          pages: pages
+        )
+
+        response = post("/v2/player/program/over-specification-check", params: payload)
+        Objects::Solutions::OverSpecDetectionResult.new(response || {})
+      end
+
+      private
+
+      def compact_hash(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          next if value.nil?
+
+          result[key] = value
+        end
+      end
+
+      def build_publish_result(response)
+        Objects::Solutions::PublishResult.new(response || {})
+      end
+
+      def validate_presence!(value, field)
+        return unless value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+        raise ArgumentError, "#{field} is required"
+      end
+
+      def validate_boolean!(value, field)
+        return if [true, false].include?(value)
+
+        raise ArgumentError, "#{field} must be true or false"
+      end
+    end
+  end
+end

data/lib/novacloud_client/support/key_transform.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module NovacloudClient
+  module Support
+    # Utilities for converting snake_case hashes to camelCase payloads.
+    module KeyTransform
+      module_function
+
+      def camelize_component(component)
+        case component
+        when Hash
+          component.each_with_object({}) do |(key, value), result|
+            result[camelize_key(key)] = camelize_component(value)
+          end
+        when Array
+          component.map { |item| camelize_component(item) }
+        else
+          component.respond_to?(:to_h) ? camelize_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").gsub("-", "_").downcase
+        parts = normalized.split("_")
+        parts.map.with_index { |segment, index| index.zero? ? segment : segment.capitalize }.join
+      end
+    end
+  end
+end

data/lib/novacloud_client/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module NovacloudClient
+  VERSION = "0.1.0"
+end

data/lib/novacloud_client.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+require_relative "novacloud_client/version"
+require_relative "novacloud_client/errors"
+require_relative "novacloud_client/configuration"
+require_relative "novacloud_client/client"

data/sig/novacloud_client.rbs

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