command_tower 0.3.1 → 0.10.0

data/app/services/command_tower/messaging/preferences/update.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      class Update
+        def self.call(...)
+          new(...).call
+        end
+
+        def initialize(
+          recipient_id:,
+          notification_type_key:,
+          preference_state:,
+          platform_enabled_channels: []
+        )
+          @recipient_id = recipient_id
+          @notification_type_key = notification_type_key.to_s
+          @preference_state = preference_state
+          @platform_enabled_channels = Array(platform_enabled_channels).map(&:to_s).freeze
+        end
+
+        def call
+          declaration = lookup_declaration!
+          validate_settings_visible!(declaration)
+          validate_writable!(declaration)
+
+          if reset_request?
+            persist_reset!
+          else
+            candidate = build_candidate_state!(declaration)
+            sparse = sparsify(declaration, candidate)
+            persist_sparse!(sparse)
+          end
+
+          evaluation = Resolve.call(
+            notification_type_key: @notification_type_key,
+            recipient_id: @recipient_id,
+            platform_enabled_channels: @platform_enabled_channels,
+          )
+
+          build_notification_result(declaration, evaluation, recipient_ready_channel_keys)
+        end
+
+        private
+
+        def recipient_ready_channel_keys
+          RecipientReadiness.for_recipient(
+            recipient_id: @recipient_id,
+            platform_enabled_channels: @platform_enabled_channels,
+          ).recipient_ready_channel_keys
+        rescue RecipientReadiness::RecipientNotFoundError
+          []
+        end
+
+        def lookup_declaration!
+          NotificationTypes.lookup(@notification_type_key)
+        rescue NotificationTypes::NotFoundError
+          raise UnknownTypeError, "notification type not registered: #{@notification_type_key}"
+        end
+
+        def validate_settings_visible!(declaration)
+          return if declaration.settings_visible
+
+          raise NotSettingsVisibleError,
+                "notification type is not settings-visible: #{declaration.key}"
+        end
+
+        def validate_writable!(declaration)
+          return if declaration.user_configurable
+
+          raise InvalidPreferenceWriteError,
+                "notification type is not user-configurable: #{declaration.key}"
+        end
+
+        def reset_request?
+          return true if @preference_state.nil?
+
+          @preference_state.respond_to?(:to_h) && @preference_state.to_h.empty?
+        end
+
+        def build_candidate_state!(declaration)
+          unless @preference_state.respond_to?(:to_h)
+            raise InvalidPreferenceStateError, "preference_state must be a hash-like object"
+          end
+
+          hash = @preference_state.to_h.transform_keys(&:to_s)
+          unknown_keys = hash.keys - %w[channels inbox]
+          if unknown_keys.any?
+            raise InvalidPreferenceWriteError,
+                  "unsupported preference keys: #{unknown_keys.join(', ')}"
+          end
+
+          channels = parse_channels!(declaration, hash["channels"])
+          inbox = parse_inbox!(declaration, hash)
+
+          PreferenceState.new(channels: channels.freeze, inbox:).freeze
+        end
+
+        def parse_channels!(declaration, channels_raw)
+          return {}.freeze if channels_raw.nil?
+
+          unless channels_raw.respond_to?(:to_h)
+            raise InvalidPreferenceStateError, "preference_state channels must be a hash-like object"
+          end
+
+          channels = {}
+          channels_raw.to_h.each do |raw_key, raw_value|
+            key = raw_key.to_s
+            unless declaration.allowed_channels.include?(key)
+              raise InvalidPreferenceWriteError,
+                    "preference channels outside allowed set: #{key}"
+            end
+            unless [true, false].include?(raw_value)
+              raise InvalidPreferenceStateError,
+                    "preference channel values must be boolean: #{key}"
+            end
+
+            channels[key] = raw_value
+          end
+          channels
+        end
+
+        def parse_inbox!(declaration, hash)
+          return nil unless hash.key?("inbox")
+
+          unless [true, false].include?(hash["inbox"])
+            raise InvalidPreferenceStateError, "preference inbox must be a boolean"
+          end
+
+          unless declaration.inbox_available
+            raise InvalidPreferenceWriteError,
+                  "inbox preference is not available for notification type: #{declaration.key}"
+          end
+
+          hash["inbox"]
+        end
+
+        def sparsify(declaration, candidate)
+          defaults = PreferenceState.from_declaration_default(declaration.default_preference_state)
+          sparse_channels = {}
+
+          candidate.channels.each do |channel, enabled|
+            default_enabled = defaults.channel_enabled?(channel, default: true)
+            sparse_channels[channel] = enabled unless enabled == default_enabled
+          end
+
+          sparse_inbox =
+            if candidate.inbox.nil?
+              nil
+            elsif candidate.inbox == defaults.inbox
+              nil
+            else
+              candidate.inbox
+            end
+
+          return nil if sparse_channels.empty? && sparse_inbox.nil?
+
+          PreferenceState.new(channels: sparse_channels.freeze, inbox: sparse_inbox).freeze
+        end
+
+        def persist_reset!
+          current = Store.find(
+            recipient_id: @recipient_id,
+            notification_type_key: @notification_type_key,
+          )
+          return if current.nil?
+
+          ActiveRecord::Base.transaction do
+            Store.delete!(
+              recipient_id: @recipient_id,
+              notification_type_key: @notification_type_key,
+            )
+          end
+        end
+
+        def persist_sparse!(sparse)
+          current = Store.find(
+            recipient_id: @recipient_id,
+            notification_type_key: @notification_type_key,
+          )
+
+          if sparse.nil?
+            return if current.nil?
+
+            ActiveRecord::Base.transaction do
+              Store.delete!(
+                recipient_id: @recipient_id,
+                notification_type_key: @notification_type_key,
+              )
+            end
+            return
+          end
+
+          return if same_stored_state?(current, sparse)
+
+          ActiveRecord::Base.transaction do
+            Store.upsert!(
+              recipient_id: @recipient_id,
+              notification_type_key: @notification_type_key,
+              preference_state: sparse.to_raw_hash,
+            )
+          end
+        end
+
+        def same_stored_state?(current, sparse)
+          return false if current.nil?
+
+          current.to_raw_hash == sparse.to_raw_hash
+        end
+
+        def build_notification_result(declaration, evaluation, recipient_ready_keys)
+          effective_state = evaluation.effective_preference_state || {}
+          effective_channels = effective_state["channels"] || {}
+          channels =
+            declaration.allowed_channels.to_h do |channel|
+              [channel, !!effective_channels[channel]]
+            end
+
+          inbox_enabled =
+            if effective_state.key?("inbox")
+              !!effective_state["inbox"]
+            else
+              evaluation.inbox_permitted
+            end
+
+          available =
+            declaration.allowed_channels & @platform_enabled_channels & recipient_ready_keys
+
+          ::CommandTower::Messaging::Preferences::CatalogNotificationResult.build(
+            key: declaration.key,
+            label: declaration.label,
+            description: declaration.description,
+            order: declaration.type_order,
+            configurable: declaration.user_configurable,
+            mandatory: declaration.mandatory,
+            inbox_available: declaration.inbox_available,
+            allowed_channels: declaration.allowed_channels,
+            available_channels: available,
+            inbox_enabled:,
+            channels:,
+            stored_override_present: evaluation.stored_override_present,
+          )
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/preferences.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      module_function
+
+      def evaluate(
+        notification_type_key:,
+        recipient_id:,
+        preference_state: nil,
+        platform_enabled_channels: []
+      )
+        Evaluator.call(
+          notification_type_key:,
+          recipient_id:,
+          preference_state:,
+          platform_enabled_channels:,
+        )
+      end
+
+      def resolve(
+        notification_type_key:,
+        recipient_id:,
+        platform_enabled_channels: []
+      )
+        Resolve.call(
+          notification_type_key:,
+          recipient_id:,
+          platform_enabled_channels:,
+        )
+      end
+
+      def catalog(recipient_id:, platform_enabled_channels: [])
+        Catalog.call(
+          recipient_id:,
+          platform_enabled_channels:,
+        )
+      end
+
+      def find_stored(recipient_id:, notification_type_key:)
+        Store.find(recipient_id:, notification_type_key:)
+      end
+
+      def upsert_stored!(recipient_id:, notification_type_key:, preference_state:)
+        Store.upsert!(recipient_id:, notification_type_key:, preference_state:)
+      end
+
+      def delete_stored!(recipient_id:, notification_type_key:)
+        Store.delete!(recipient_id:, notification_type_key:)
+      end
+
+      def update(
+        recipient_id:,
+        notification_type_key:,
+        preference_state:,
+        platform_enabled_channels: []
+      )
+        Update.call(
+          recipient_id:,
+          notification_type_key:,
+          preference_state:,
+          platform_enabled_channels:,
+        )
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/pushover/adapters/disabled_adapter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Pushover
+      module Adapters
+        # Fail-closed default. Never contacts the provider.
+        class DisabledAdapter
+          def validate_user!(user_key:, application_token:)
+            Result.failure(
+              error_code: :adapter_disabled,
+              error_message: "Pushover verification adapter is disabled",
+            )
+          end
+
+          def send_test_notification!(user_key:, application_token:, title:, message:)
+            Result.failure(
+              error_code: :adapter_disabled,
+              error_message: "Pushover verification adapter is disabled",
+            )
+          end
+
+          def send_message!(user_key:, application_token:, title:, message:)
+            Result.failure(
+              error_code: :adapter_disabled,
+              error_message: "Pushover delivery adapter is disabled",
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/pushover/adapters/fake_adapter.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Pushover
+      module Adapters
+        # In-memory / no-network adapter for tests and local development.
+        # Inject failures via FakeAdapter.fail_with = :invalid_user | :invalid_token |
+        # :invalid_credentials | :timeout | :provider_unavailable | :rate_limited
+        class FakeAdapter
+          class << self
+            attr_accessor :validations, :test_notifications, :messages, :fail_with
+
+            def reset!
+              self.validations = []
+              self.test_notifications = []
+              self.messages = []
+              self.fail_with = nil
+            end
+          end
+
+          self.reset!
+
+          def validate_user!(user_key:, application_token:)
+            failure = injected_failure
+            return failure if failure
+
+            self.class.validations << {
+              user_key_present: user_key.to_s.present?,
+              application_token_present: application_token.to_s.present?,
+            }
+            Result.ok
+          end
+
+          def send_test_notification!(user_key:, application_token:, title:, message:)
+            failure = injected_failure
+            return failure if failure
+
+            self.class.test_notifications << {
+              user_key_present: user_key.to_s.present?,
+              application_token_present: application_token.to_s.present?,
+              title: title.to_s,
+              message: message.to_s,
+            }
+            Result.ok
+          end
+
+          def send_message!(user_key:, application_token:, title:, message:)
+            failure = injected_failure
+            return failure if failure
+
+            self.class.messages << {
+              user_key_present: user_key.to_s.present?,
+              application_token_present: application_token.to_s.present?,
+              title: title.to_s,
+              message: message.to_s,
+            }
+            Result.ok(provider_request_id: "fake-request-#{self.class.messages.size}")
+          end
+
+          private
+
+          def injected_failure
+            case self.class.fail_with
+            when :invalid_user
+              Result.failure(error_code: :invalid_user, error_message: "Pushover user key is invalid")
+            when :invalid_token
+              Result.failure(error_code: :invalid_token, error_message: "Pushover application token is invalid")
+            when :invalid_credentials
+              Result.failure(error_code: :invalid_credentials, error_message: "Pushover credentials were rejected")
+            when :timeout
+              Result.failure(error_code: :timeout, error_message: "Pushover provider timed out")
+            when :provider_unavailable
+              Result.failure(error_code: :provider_unavailable, error_message: "Pushover provider unavailable")
+            when :rate_limited
+              Result.failure(error_code: :rate_limited, error_message: "Pushover provider rate limited the request")
+            when NilClass
+              nil
+            else
+              Result.failure(
+                error_code: self.class.fail_with.to_sym,
+                error_message: "Pushover provider rejected the request",
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/pushover/adapters/http_adapter.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module CommandTower
+  module Messaging
+    module Pushover
+      module Adapters
+        # Real Pushover HTTP client for credential validation, test notifications,
+        # and production delivery. Never returns or logs secrets / raw provider payloads.
+        class HttpAdapter
+          def validate_user!(user_key:, application_token:)
+            post_form(
+              path: "users/validate.json",
+              form: {
+                "token" => application_token.to_s,
+                "user" => user_key.to_s,
+              },
+            )
+          end
+
+          def send_test_notification!(user_key:, application_token:, title:, message:)
+            post_form(
+              path: "messages.json",
+              form: {
+                "token" => application_token.to_s,
+                "user" => user_key.to_s,
+                "title" => title.to_s,
+                "message" => message.to_s,
+              },
+            )
+          end
+
+          def send_message!(user_key:, application_token:, title:, message:)
+            post_form(
+              path: "messages.json",
+              form: {
+                "token" => application_token.to_s,
+                "user" => user_key.to_s,
+                "title" => title.to_s,
+                "message" => message.to_s,
+              },
+            )
+          end
+
+          private
+
+          def post_form(path:, form:)
+            config = CommandTower.config.messaging.pushover
+            uri = URI.join("#{config.api_base_url.to_s.chomp('/')}/", path)
+            timeout = config.timeout_seconds.to_i
+            timeout = 5 if timeout <= 0
+
+            request = Net::HTTP::Post.new(uri)
+            request.set_form_data(form)
+
+            response = Net::HTTP.start(
+              uri.hostname,
+              uri.port,
+              use_ssl: uri.scheme == "https",
+              open_timeout: timeout,
+              read_timeout: timeout,
+            ) do |http|
+              http.request(request)
+            end
+
+            classify_response(response)
+          rescue Net::OpenTimeout, Net::ReadTimeout
+            Result.failure(error_code: :timeout, error_message: "Pushover provider timed out")
+          rescue StandardError
+            Result.failure(error_code: :provider_unavailable, error_message: "Pushover provider unavailable")
+          end
+
+          def classify_response(response)
+            status = response.code.to_i
+            body = parse_json(response.body)
+            status_ok = body.is_a?(Hash) && body["status"].to_i == 1
+            request_id = body.is_a?(Hash) ? body["request"].to_s.presence : nil
+
+            if response.is_a?(Net::HTTPSuccess) && status_ok
+              return Result.ok(provider_request_id: request_id)
+            end
+
+            errors = Array(body.is_a?(Hash) ? body["errors"] : nil).map(&:to_s)
+            joined = errors.join(" ").downcase
+
+            if status == 429
+              return Result.failure(
+                error_code: :rate_limited,
+                error_message: "Pushover provider rate limited the request",
+                provider_request_id: request_id,
+              )
+            end
+
+            if joined.include?("application token") || joined.include?("app token") || joined.include?("invalid token")
+              return Result.failure(
+                error_code: :invalid_token,
+                error_message: "Pushover application token is invalid",
+                provider_request_id: request_id,
+              )
+            end
+
+            if joined.include?("user key") || joined.include?("user is invalid") || joined.include?("user key is invalid")
+              return Result.failure(
+                error_code: :invalid_user,
+                error_message: "Pushover user key is invalid",
+                provider_request_id: request_id,
+              )
+            end
+
+            if status == 400
+              return Result.failure(
+                error_code: :invalid_credentials,
+                error_message: "Pushover credentials were rejected",
+                provider_request_id: request_id,
+              )
+            end
+
+            if status >= 500
+              return Result.failure(
+                error_code: :provider_unavailable,
+                error_message: "Pushover provider unavailable",
+                provider_request_id: request_id,
+              )
+            end
+
+            Result.failure(
+              error_code: :provider_unavailable,
+              error_message: "Pushover provider rejected the request",
+              provider_request_id: request_id,
+            )
+          end
+
+          def parse_json(body)
+            JSON.parse(body.to_s)
+          rescue JSON::ParserError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/pushover/adapters/log_adapter.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Pushover
+      module Adapters
+        # Dev-only log adapter. Emits safe metadata only; never secrets.
+        class LogAdapter
+          def validate_user!(user_key:, application_token:)
+            Rails.logger.info(
+              {
+                component: "command_tower.messaging",
+                event: "messaging.pushover.log_adapter.validate_user",
+                user_key_length: user_key.to_s.length,
+                application_token_length: application_token.to_s.length,
+              }.to_json,
+            )
+            Result.ok
+          end
+
+          def send_test_notification!(user_key:, application_token:, title:, message:)
+            Rails.logger.info(
+              {
+                component: "command_tower.messaging",
+                event: "messaging.pushover.log_adapter.send_test_notification",
+                user_key_length: user_key.to_s.length,
+                application_token_length: application_token.to_s.length,
+                title_length: title.to_s.length,
+                message_length: message.to_s.length,
+              }.to_json,
+            )
+            Result.ok
+          end
+
+          def send_message!(user_key:, application_token:, title:, message:)
+            Rails.logger.info(
+              {
+                component: "command_tower.messaging",
+                event: "messaging.pushover.log_adapter.send_message",
+                user_key_length: user_key.to_s.length,
+                application_token_length: application_token.to_s.length,
+                title_length: title.to_s.length,
+                message_length: message.to_s.length,
+              }.to_json,
+            )
+            Result.ok(provider_request_id: "log-message")
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/pushover/result.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Pushover
+      # Provider-call result. Never includes secrets or raw provider payloads.
+      Result = Struct.new(
+        :success?,
+        :error_code,
+        :error_message,
+        :provider_request_id,
+        keyword_init: true,
+      ) do
+        def self.ok(provider_request_id: nil)
+          new(
+            success?: true,
+            error_code: nil,
+            error_message: nil,
+            provider_request_id: provider_request_id&.to_s.presence,
+          )
+        end
+
+        def self.failure(error_code:, error_message:, provider_request_id: nil)
+          new(
+            success?: false,
+            error_code: error_code.to_sym,
+            error_message: error_message.to_s,
+            provider_request_id: provider_request_id&.to_s.presence,
+          )
+        end
+      end
+    end
+  end
+end