novacloud_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 59ea901e539b0594fc46cb945244af7b0b1435d6c636d8faad0ee2ca185d2958
+  data.tar.gz: ede71795f8cda337f5c6ca715a156a46bdfd9300f0f6426a06510ddc8210d4ad
+SHA512:
+  metadata.gz: f8215e3cdca0858e12d65d7f100bad2b4ca13e987631f95e973d511dcb4de902251124d309c7f5abff2b098cfe8b31d99bd4b0fe9f7e1e4aae5a1e5585a7835f
+  data.tar.gz: c605efa841060bba5a18fb413c549acc05e0413952751b5f57c4dd50fd17202c5f42bb15210e4bbf0dc89dce8b92828b472dc26e128ae8238cdd25393d4cabda

data/.rubocop_todo.yml

@@ -0,0 +1,5 @@
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/ClassLength:
+  Max: 200

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-10-26
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Chayut Orapinpatipat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,142 @@
+# NovaCloud Client (WIP)
+
+ Sprint 01 delivered the core HTTP client for the NovaCloud Open Platform. The gem now:
+
+- Manages configuration once (`app_key`, `app_secret`, `service_domain`).
+- Handles authentication headers automatically via Faraday middleware.
+- Maps HTTP errors to a typed exception hierarchy.
+- Normalizes GET/POST payloads and parses JSON responses.
+
+ Sprint 02 expands on this foundation with dedicated resource helpers (`client.players`, `client.control`, `client.scheduled_control`, `client.solutions`) and typed response objects (e.g., `NovacloudClient::Objects::Player`).
+
+## Resource Overview
+
+- **Players**: `list`, `statuses`, `running_status`
+- **Control**: `brightness`, `volume`, `video_source`, `screen_power`, `screen_status`, `screenshot`, `reboot`, `ntp_sync`, `synchronous_playback`, `request_result`
+- **Scheduled Control**: `screen_status`, `reboot`, `volume`, `brightness`, `video_source`
+- **Solutions**: `emergency_page`, `cancel_emergency`, `common_solution`, `offline_export`, `set_over_spec_detection`, `program_over_spec_detection`
+- **Screens** (VNNOXCare): `list`, `monitor`, `detail`
+- **Logs**: `control_history`
+
+> **Heads-up:** NovaCloud's public API docs (as of October 2025) do not expose
+> "material" endpoints for uploading, listing, or deleting media assets. This
+> client therefore expects assets to be hosted already (either uploaded via the
+> VNNOX UI or served from your own CDN) and referenced by URL in solution
+> payloads.
+
+## Quick Start
+
+```ruby
+require "novacloud_client"
+
+client = NovacloudClient::Client.new(
+  app_key: "YOUR_APP_KEY",
+  app_secret: "YOUR_APP_SECRET",
+  service_domain: "open-us.vnnox.com"
+)
+
+players = client.players.list(count: 20)
+first_player = players.first
+
+statuses = client.players.statuses(player_ids: players.map(&:player_id))
+
+queue = client.players.config_status(
+  player_ids: players.map(&:player_id),
+  notice_url: "https://example.com/status-webhook"
+)
+
+client.control.ntp_sync(
+  player_ids: players.map(&:player_id),
+  server: "ntp1.aliyun.com",
+  enable: true
+)
+
+client.scheduled_control.brightness(
+  player_ids: players.map(&:player_id),
+  schedules: {
+    start_date: Date.today.strftime("%Y-%m-%d"),
+    end_date: (Date.today + 30).strftime("%Y-%m-%d"),
+    exec_time: "07:00:00",
+    type: 0,
+    value: 55
+  }
+)
+
+request = client.control.brightness(
+  player_ids: players.map(&:player_id),
+  brightness: 80,
+  notice_url: "https://example.com/callback"
+)
+
+result = client.control.request_result(request_id: request.request_id)
+puts result.all_successful?
+
+screens = client.screens.list(status: 1)
+puts screens.first.name
+
+client.solutions.emergency_page(
+  player_ids: [first_player.player_id],
+  attribute: { duration: 20_000, normal_program_status: "PAUSE", spots_type: "IMMEDIATELY" },
+  page: {
+    name: "urgent-alert",
+    widgets: [
+      {
+        type: "PICTURE",
+        z_index: 1,
+        duration: 10_000,
+        url: "https://example.com/alert.png",
+        layout: { x: "0%", y: "0%", width: "100%", height: "100%" }
+      }
+    ]
+  }
+)
+
+offline_bundle = client.solutions.offline_export(
+  program_type: 1,
+  plan_version: "V2",
+  pages: [
+    {
+      name: "main",
+      widgets: [
+        { type: "PICTURE", md5: "abc", url: "https://cdn.example.com/img.jpg" }
+      ]
+    }
+  ]
+)
+
+puts offline_bundle.plan_json.url
+
+over_spec_result = client.solutions.program_over_spec_detection(
+  player_ids: [first_player.player_id],
+  pages: [
+    {
+      page_id: 1,
+      widgets: [
+        { widget_id: 1, type: "VIDEO", url: "https://cdn.example.com/video.mp4", width: "3840", height: "2160" }
+      ]
+    }
+  ]
+)
+
+if over_spec_result.items.any?(&:over_spec?)
+  warn "Program exceeds specifications"
+end
+```
+
+### Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+### Documentation
+
+Run YARD to generate HTML API documentation for the gem:
+
+```bash
+bundle exec yard doc
+```
+
+Then browse the docs via the generated `doc/index.html` or launch a local server with `bundle exec yard server --reload`.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/novacloud_client/client.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+require_relative "errors"
+require_relative "configuration"
+require_relative "middleware/authentication"
+require_relative "middleware/error_handler"
+require_relative "resources/players"
+require_relative "resources/control"
+require_relative "resources/scheduled_control"
+require_relative "resources/solutions"
+require_relative "resources/screens"
+require_relative "resources/logs"
+
+module NovacloudClient
+  # Central entry point for interacting with the NovaCloud API.
+  class Client
+    attr_reader :config
+
+    def initialize(app_key:, app_secret:, service_domain:, &faraday_block)
+      @config = Configuration.new
+      @config.app_key = app_key
+      @config.app_secret = app_secret
+      @config.service_domain = service_domain
+      @config.validate!
+
+      @faraday_block = faraday_block
+    end
+
+    def connection
+      @connection ||= build_connection
+    end
+
+    def request(http_method:, endpoint:, params: {})
+      symbolized_method = http_method.to_sym
+      response = connection.public_send(symbolized_method) do |req|
+        req.url endpoint
+        apply_request_payload(req, symbolized_method, params)
+      end
+
+      parse_body(response)
+    end
+
+    def players
+      @players ||= Resources::Players.new(self)
+    end
+
+    def control
+      @control ||= Resources::Control.new(self)
+    end
+
+    def scheduled_control
+      @scheduled_control ||= Resources::ScheduledControl.new(self)
+    end
+
+    def solutions
+      @solutions ||= Resources::Solutions.new(self)
+    end
+
+    def screens
+      @screens ||= Resources::Screens.new(self)
+    end
+
+    def logs
+      @logs ||= Resources::Logs.new(self)
+    end
+
+    private
+
+    def build_connection
+      Faraday.new(url: config.base_url) do |faraday|
+        faraday.headers["Accept"] = "application/json"
+
+        faraday.use Middleware::Authentication,
+                    app_key: config.app_key,
+                    app_secret: config.app_secret
+        faraday.use Middleware::ErrorHandler
+
+        @faraday_block&.call(faraday)
+
+        faraday.adapter config.adapter
+      end
+    end
+
+    def apply_request_payload(request, http_method, params)
+      return if params.empty?
+
+      case http_method
+      when :get, :delete
+        request.params.update(params)
+      else
+        request.headers["Content-Type"] = "application/json; charset=utf-8"
+        request.body = JSON.generate(params)
+      end
+    end
+
+    def parse_body(response)
+      body = response.body
+      return nil if body.nil?
+      return body unless body.is_a?(String)
+      return nil if body.strip.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+  end
+end

data/lib/novacloud_client/configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module NovacloudClient
+  # Holds configuration for a NovacloudClient::Client instance.
+  class Configuration
+    attr_accessor :app_key, :app_secret, :service_domain, :adapter
+
+    def initialize
+      @adapter = :net_http
+    end
+
+    def base_url
+      "https://#{service_domain}"
+    end
+
+    def validate!
+      raise ArgumentError, "app_key is required" if blank?(app_key)
+      raise ArgumentError, "app_secret is required" if blank?(app_secret)
+      raise ArgumentError, "service_domain is required" if blank?(service_domain)
+    end
+
+    private
+
+    def blank?(value)
+      return true if value.nil?
+      return value.strip.empty? if value.is_a?(String)
+
+      value.respond_to?(:empty?) ? value.empty? : false
+    end
+  end
+end

data/lib/novacloud_client/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module NovacloudClient
+  # Base error class allowing access to the Faraday environment.
+  class Error < StandardError
+    attr_reader :response
+
+    def initialize(message = nil, response: nil)
+      super(message)
+      @response = response
+    end
+  end
+
+  class ClientError < Error; end
+  class BadRequestError < ClientError; end
+  class AuthenticationError < ClientError; end
+  class PermissionError < ClientError; end
+  class NotAcceptableError < ClientError; end
+  class RateLimitError < ClientError; end
+
+  class ServerError < Error; end
+  class InternalServerError < ServerError; end
+  class BadGatewayError < ServerError; end
+  class ServiceUnavailableError < ServerError; end
+  class GatewayTimeoutError < ServerError; end
+end

data/lib/novacloud_client/middleware/authentication.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "digest"
+require "securerandom"
+
+module NovacloudClient
+  module Middleware
+    # Injects the NovaCloud authentication headers into every request.
+    class Authentication < Faraday::Middleware
+      def initialize(app, app_key:, app_secret:)
+        super(app)
+        @app_key = app_key
+        @app_secret = app_secret
+      end
+
+      def call(env)
+        cur_time = current_utc_timestamp
+        nonce = generate_nonce
+        checksum = checksum_for(nonce, cur_time)
+
+        headers = env.request_headers
+        headers["AppKey"] = @app_key
+        headers["Nonce"] = nonce
+        headers["CurTime"] = cur_time
+        headers["CheckSum"] = checksum
+
+        @app.call(env)
+      end
+
+      private
+
+      def current_utc_timestamp
+        Time.now.utc.to_i.to_s
+      end
+
+      def generate_nonce
+        timestamp_component = (Time.now.utc.to_f * 1_000_000).to_i.to_s(36)
+        random_component = SecureRandom.alphanumeric(16)
+        (timestamp_component + random_component)[0, 16]
+      end
+
+      def checksum_for(nonce, cur_time)
+        signature = @app_secret + nonce + cur_time
+        Digest::SHA256.hexdigest(signature)
+      end
+    end
+  end
+end

data/lib/novacloud_client/middleware/error_handler.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+require_relative "../errors"
+
+module NovacloudClient
+  module Middleware
+    # Maps HTTP error responses to NovacloudClient exception classes.
+    class ErrorHandler < Faraday::Middleware
+      ERROR_MAP = {
+        400 => NovacloudClient::BadRequestError,
+        401 => NovacloudClient::AuthenticationError,
+        403 => NovacloudClient::PermissionError,
+        406 => NovacloudClient::NotAcceptableError,
+        429 => NovacloudClient::RateLimitError,
+        500 => NovacloudClient::InternalServerError,
+        502 => NovacloudClient::BadGatewayError,
+        503 => NovacloudClient::ServiceUnavailableError,
+        504 => NovacloudClient::GatewayTimeoutError
+      }.freeze
+
+      def call(env)
+        @app.call(env).on_complete do |response_env|
+          handle_response(response_env)
+        end
+      end
+
+      private
+
+      def handle_response(env)
+        status = env.status.to_i
+        return if (200..299).cover?(status)
+
+        error_class = ERROR_MAP[status] || fallback_error(status)
+        message = "HTTP #{status}: #{summary_from(env)}"
+        raise error_class.new(message, response: env)
+      end
+
+      def fallback_error(status)
+        if (400..499).cover?(status)
+          NovacloudClient::ClientError
+        else
+          NovacloudClient::ServerError
+        end
+      end
+
+      def summary_from(env)
+        body = env.body
+        return "No response body" if body.nil?
+
+        if body.is_a?(String)
+          body.strip.empty? ? "Empty body" : body.strip[0, 200]
+        elsif body.respond_to?(:to_json)
+          body.to_json[0, 200]
+        else
+          body.to_s[0, 200]
+        end
+      end
+    end
+  end
+end

data/lib/novacloud_client/objects/base.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "time"
+
+module NovacloudClient
+  module Objects
+    # Base class providing attribute assignment and coercion helpers.
+    class Base
+      def initialize(attributes = {})
+        assign_attributes(attributes)
+      end
+
+      private
+
+      def assign_attributes(attributes)
+        attributes.each do |key, value|
+          writer = "#{key}="
+          if respond_to?(writer)
+            public_send(writer, value)
+            next
+          end
+
+          normalized_writer = normalize_writer(key)
+          next if normalized_writer == writer
+
+          public_send(normalized_writer, value) if respond_to?(normalized_writer)
+        end
+      end
+
+      def parse_timestamp(value)
+        return nil if value.nil?
+        return value if value.is_a?(Time)
+
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        value
+      end
+
+      def normalize_writer(key)
+        normalized = key.to_s
+        normalized = normalized.gsub(/([A-Z\d]+)([A-Z][a-z])/, "\\1_\\2")
+                               .gsub(/([a-z\d])([A-Z])/, "\\1_\\2")
+                               .tr("-", "_")
+                               .downcase
+        "#{normalized}="
+      end
+    end
+  end
+end

data/lib/novacloud_client/objects/control_log_entry.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module NovacloudClient
+  module Objects
+    # Represents an execution record for a remote control command.
+    class ControlLogEntry < Base
+      attr_accessor :status, :type
+      attr_reader :execute_time
+
+      def execute_time=(value)
+        @execute_time = parse_timestamp(value)
+      end
+
+      def success?
+        status.to_i.zero? ? false : status.to_i == 1
+      end
+    end
+  end
+end

data/lib/novacloud_client/objects/control_result.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module NovacloudClient
+  module Objects
+    # Represents the result of a control or queued request returning success/fail lists.
+    class ControlResult < Base
+      attr_reader :successes, :failures
+
+      def initialize(attributes = {})
+        @successes = []
+        @failures = []
+        super
+      end
+
+      def success=(value)
+        @successes = Array(value)
+      end
+
+      def fail=(value)
+        @failures = Array(value)
+      end
+
+      def all_successful?
+        failures.empty?
+      end
+
+      def partial_success?
+        successes.any? && failures.any?
+      end
+
+      def all_failed?
+        successes.empty?
+      end
+
+      def success_count
+        successes.size
+      end
+
+      def failure_count
+        failures.size
+      end
+
+      # Maintain API compatibility with camelCase keys.
+      def success
+        successes
+      end
+
+      def fail
+        failures
+      end
+    end
+  end
+end

data/lib/novacloud_client/objects/player.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module NovacloudClient
+  module Objects
+    # Represents a player returned from NovaCloud player APIs.
+    class Player < Base
+      attr_accessor :player_id, :player_type, :name, :sn, :version, :ip
+      attr_reader :last_online_time, :online_status
+
+      def last_online_time=(value)
+        @last_online_time = parse_timestamp(value)
+      end
+
+      def online_status=(value)
+        @online_status = value.to_i
+      end
+
+      def online?
+        online_status == 1
+      end
+
+      def offline?
+        !online?
+      end
+
+      def synchronous?
+        player_type.to_i == 1
+      end
+
+      def asynchronous?
+        player_type.to_i == 2
+      end
+    end
+  end
+end

data/lib/novacloud_client/objects/player_status.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module NovacloudClient
+  module Objects
+    # Represents basic status information for a player.
+    class PlayerStatus < Base
+      attr_accessor :player_id, :sn
+      attr_reader :online_status, :last_online_time
+
+      def online_status=(value)
+        @online_status = value.to_i
+      end
+
+      def last_online_time=(value)
+        @last_online_time = parse_timestamp(value)
+      end
+
+      def online?
+        online_status == 1
+      end
+
+      def offline?
+        !online?
+      end
+    end
+  end
+end

data/lib/novacloud_client/objects/queued_request.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "control_result"
+
+module NovacloudClient
+  module Objects
+    # Represents the enqueue result for asynchronous player commands.
+    class QueuedRequest < ControlResult
+      attr_reader :request_id
+
+      # Queue responses include a request ID used to poll for results later.
+      def request_id=(value)
+        @request_id = value&.to_s
+      end
+    end
+  end
+end