command_tower 0.4.0 → 0.10.0

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Pushover
+      # Selects Pushover provider transport from config. Provider ops only —
+      # verification and delivery. Does not query endpoints, preferences, or
+      # create DeliveryAttempts.
+      module Transport
+        class << self
+          attr_writer :adapter
+
+          def adapter
+            @adapter ||= build_adapter
+          end
+
+          def reset_adapter!
+            @adapter = nil
+          end
+
+          def validate_user!(user_key:, application_token:)
+            adapter.validate_user!(user_key:, application_token:)
+          end
+
+          def send_test_notification!(user_key:, application_token:, title:, message:)
+            adapter.send_test_notification!(
+              user_key:,
+              application_token:,
+              title:,
+              message:,
+            )
+          end
+
+          def send_message!(user_key:, application_token:, title:, message:)
+            adapter.send_message!(
+              user_key:,
+              application_token:,
+              title:,
+              message:,
+            )
+          end
+
+          private
+
+          def build_adapter
+            name = CommandTower.config.messaging.pushover.adapter.to_s
+            case name
+            when "fake"
+              Adapters::FakeAdapter.new
+            when "log"
+              Adapters::LogAdapter.new
+            when "http"
+              Adapters::HttpAdapter.new
+            when "disabled"
+              Adapters::DisabledAdapter.new
+            else
+              Adapters::DisabledAdapter.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/recipient_readiness/channel_result.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module RecipientReadiness
+      ChannelResult = Data.define(
+        :channel_key,
+        :ready,
+        :platform_enabled,
+        :platform_configured,
+        :recipient_ready,
+        :status,
+        :reason_codes,
+        :endpoint_count,
+        :eligible_endpoint_count,
+        :eligible_endpoint_ids,
+        :resolved_endpoint_id,
+        :verification_required,
+        :evaluated_at,
+      ) do
+        def self.build(
+          channel_key:,
+          ready:,
+          platform_enabled:,
+          platform_configured:,
+          recipient_ready:,
+          status:,
+          reason_codes:,
+          endpoint_count:,
+          eligible_endpoint_count:,
+          eligible_endpoint_ids:,
+          verification_required:,
+          resolved_endpoint_id: nil,
+          evaluated_at: Time.current
+        )
+          new(
+            channel_key: channel_key.to_s,
+            ready: !!ready,
+            platform_enabled: !!platform_enabled,
+            platform_configured: !!platform_configured,
+            recipient_ready: !!recipient_ready,
+            status: status.to_s,
+            reason_codes: Array(reason_codes).map(&:to_s).freeze,
+            endpoint_count: Integer(endpoint_count),
+            eligible_endpoint_count: Integer(eligible_endpoint_count),
+            eligible_endpoint_ids: Array(eligible_endpoint_ids).map { |id| Integer(id) }.freeze,
+            resolved_endpoint_id: resolved_endpoint_id.nil? ? nil : Integer(resolved_endpoint_id),
+            verification_required: !!verification_required,
+            evaluated_at:,
+          ).freeze
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/recipient_readiness/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module RecipientReadiness
+      class Error < StandardError; end
+    end
+  end
+end

data/app/services/command_tower/messaging/recipient_readiness/evaluate.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module RecipientReadiness
+      class Evaluate
+        def self.for_channel(recipient_id:, channel_key:, platform_enabled_channels: [])
+          new(
+            recipient_id:,
+            platform_enabled_channels:,
+          ).for_channel(channel_key)
+        end
+
+        def self.for_recipient(recipient_id:, platform_enabled_channels: [])
+          new(
+            recipient_id:,
+            platform_enabled_channels:,
+          ).for_recipient
+        end
+
+        def initialize(recipient_id:, platform_enabled_channels: [])
+          @recipient_id = recipient_id
+          @platform_enabled_channels = Array(platform_enabled_channels).map(&:to_s).freeze
+          @evaluated_at = Time.current
+        end
+
+        def for_channel(channel_key)
+          key = channel_key.to_s
+          definition = Channels.fetch(key)
+          raise UnknownChannelError, "unknown channel: #{key.inspect}" if definition.nil?
+
+          user = load_user!
+          result = evaluate_definition(definition, user)
+          log_evaluation(result)
+          result
+        end
+
+        def for_recipient
+          user = load_user!
+          channels = {}
+
+          Channels.definitions.each do |definition|
+            channels[definition.key] = evaluate_definition(definition, user)
+          end
+
+          result = RecipientResult.build(
+            recipient_id: @recipient_id,
+            channels:,
+            evaluated_at: @evaluated_at,
+          )
+          channels.each_value { |channel_result| log_evaluation(channel_result) }
+          result
+        end
+
+        private
+
+        def load_user!
+          user = ::User.find_by(id: @recipient_id)
+          raise RecipientNotFoundError, "recipient not found: #{@recipient_id.inspect}" if user.nil?
+
+          user
+        end
+
+        def evaluate_definition(definition, user)
+          key = definition.key
+          platform_enabled = platform_enabled_for?(definition)
+          platform_configured = platform_configured_for?(definition)
+
+          recipient =
+            if definition.inbox?
+              evaluate_inbox(user)
+            elsif definition.identity_backed
+              evaluate_identity(definition, user)
+            elsif definition.supports_endpoint_records
+              evaluate_endpoints(key)
+            else
+              empty_recipient_result
+            end
+
+          reason_codes = []
+          reason_codes << ReasonCodes::PLATFORM_DISABLED unless platform_enabled
+          reason_codes << ReasonCodes::PLATFORM_UNCONFIGURED unless platform_configured
+          reason_codes.concat(recipient[:reason_codes])
+
+          recipient_ready = recipient[:recipient_ready]
+          ready = platform_enabled && platform_configured && recipient_ready
+
+          ChannelResult.build(
+            channel_key: key,
+            ready:,
+            platform_enabled:,
+            platform_configured:,
+            recipient_ready:,
+            status: ready ? "ready" : "unavailable",
+            reason_codes: reason_codes.uniq,
+            endpoint_count: recipient[:endpoint_count],
+            eligible_endpoint_count: recipient[:eligible_endpoint_count],
+            eligible_endpoint_ids: recipient[:eligible_endpoint_ids],
+            resolved_endpoint_id: recipient[:resolved_endpoint_id],
+            verification_required: recipient[:verification_required],
+            evaluated_at: @evaluated_at,
+          )
+        end
+
+        def platform_enabled_for?(definition)
+          return true if definition.inbox?
+
+          @platform_enabled_channels.include?(definition.key)
+        end
+
+        def platform_configured_for?(definition)
+          return true if definition.inbox?
+
+          CommandTower::Messaging::ChannelDetectors.configured?(definition.key)
+        end
+
+        def evaluate_inbox(_user)
+          empty_recipient_result.merge(recipient_ready: true)
+        end
+
+        def evaluate_identity(definition, user)
+          facts = IdentityFacts.for_user(user)
+
+          case definition.key
+          when "email"
+            evaluate_email_identity(facts)
+          when "sms"
+            evaluate_phone_identity(facts)
+          else
+            identity_result(false, ReasonCodes::IDENTITY_UNAVAILABLE, verification_required: true)
+          end
+        end
+
+        def evaluate_email_identity(facts)
+          unless facts.email_supported
+            return identity_unavailable_result
+          end
+          unless facts.email_present
+            return identity_result(false, ReasonCodes::IDENTITY_MISSING, verification_required: true)
+          end
+          unless facts.email_validated
+            return identity_result(false, ReasonCodes::IDENTITY_UNVERIFIED, verification_required: true)
+          end
+
+          identity_result(true, nil, verification_required: false)
+        end
+
+        def evaluate_phone_identity(facts)
+          unless facts.phone_supported
+            return identity_unavailable_result
+          end
+          unless facts.phone_present
+            return identity_result(false, ReasonCodes::IDENTITY_MISSING, verification_required: true)
+          end
+          unless facts.phone_number_validated
+            return identity_result(false, ReasonCodes::IDENTITY_UNVERIFIED, verification_required: true)
+          end
+
+          identity_result(true, nil, verification_required: false)
+        end
+
+        def identity_unavailable_result
+          identity_result(false, ReasonCodes::IDENTITY_UNAVAILABLE, verification_required: true)
+        end
+
+        def identity_result(ready, reason, verification_required:)
+          empty_recipient_result.merge(
+            recipient_ready: ready,
+            reason_codes: reason ? [reason] : [],
+            verification_required:,
+          )
+        end
+
+        def empty_recipient_result
+          {
+            recipient_ready: false,
+            reason_codes: [],
+            endpoint_count: 0,
+            eligible_endpoint_count: 0,
+            eligible_endpoint_ids: [],
+            resolved_endpoint_id: nil,
+            verification_required: false,
+          }
+        end
+
+        def evaluate_endpoints(channel_key)
+          views = Endpoints.list(owner_user_id: @recipient_id, channel_key:)
+          endpoint_count = views.size
+          eligible = views.select { |view| eligible_endpoint?(view, channel_key) }
+          eligible_ids = eligible.map(&:id)
+
+          if endpoint_count.zero?
+            return endpoint_result(
+              false,
+              ReasonCodes::ENDPOINT_MISSING,
+              endpoint_count:,
+              eligible_ids: [],
+              verification_required: true,
+            )
+          end
+
+          if eligible_ids.size == 1
+            return endpoint_result(
+              true,
+              nil,
+              endpoint_count:,
+              eligible_ids:,
+              resolved_endpoint_id: eligible_ids.first,
+              verification_required: false,
+            )
+          end
+
+          if eligible_ids.size > 1
+            # Single-active / typed-credential channels must resolve exactly one endpoint.
+            # Multi-device channels (e.g. push) remain recipient_ready without a single resolved id.
+            if Endpoint.single_active_channel?(channel_key) ||
+                Endpoint.typed_credentials_channel?(channel_key)
+              return endpoint_result(
+                false,
+                ReasonCodes::ENDPOINT_INVALID,
+                endpoint_count:,
+                eligible_ids:,
+                verification_required: false,
+              )
+            end
+
+            return endpoint_result(
+              true,
+              nil,
+              endpoint_count:,
+              eligible_ids:,
+              verification_required: false,
+            )
+          end
+
+          reason = endpoint_not_ready_reason(views, channel_key)
+          endpoint_result(
+            false,
+            reason,
+            endpoint_count:,
+            eligible_ids: [],
+            verification_required: reason != ReasonCodes::ENDPOINT_INVALID &&
+              reason != ReasonCodes::CREDENTIALS_MISSING,
+          )
+        end
+
+        def eligible_endpoint?(view, channel_key)
+          return false unless view.lifecycle_state == "active"
+          return false unless view.verification_state == "verified"
+
+          if Endpoint.typed_credentials_channel?(channel_key)
+            return false unless view.credentials_configured
+          end
+
+          true
+        end
+
+        def endpoint_not_ready_reason(views, channel_key)
+          active = views.select { |view| view.lifecycle_state == "active" }
+          if active.empty?
+            return ReasonCodes::ENDPOINT_INVALID if views.all? { |view|
+              %w[revoked invalid retired].include?(view.lifecycle_state)
+            }
+
+            return ReasonCodes::ENDPOINT_INACTIVE
+          end
+
+          if active.any? { |view| view.verification_state != "verified" }
+            return ReasonCodes::ENDPOINT_UNVERIFIED
+          end
+
+          if Endpoint.typed_credentials_channel?(channel_key) &&
+              active.any? { |view|
+                view.verification_state == "verified" && !view.credentials_configured
+              }
+            return ReasonCodes::CREDENTIALS_MISSING
+          end
+
+          ReasonCodes::ENDPOINT_INVALID
+        end
+
+        def endpoint_result(
+          ready,
+          reason,
+          endpoint_count:,
+          eligible_ids:,
+          verification_required:,
+          resolved_endpoint_id: nil
+        )
+          {
+            recipient_ready: ready,
+            reason_codes: reason ? [reason] : [],
+            endpoint_count:,
+            eligible_endpoint_count: eligible_ids.size,
+            eligible_endpoint_ids: eligible_ids,
+            resolved_endpoint_id: ready ? resolved_endpoint_id : nil,
+            verification_required:,
+          }
+        end
+
+        def log_evaluation(result)
+          Contract::Observability::StructuredLogger.info(
+            event: "messaging.recipient_readiness.evaluated",
+            recipient_id: @recipient_id,
+            channel_key: result.channel_key,
+            ready: result.ready,
+            platform_enabled: result.platform_enabled,
+            platform_configured: result.platform_configured,
+            recipient_ready: result.recipient_ready,
+            reason_codes: result.reason_codes,
+            eligible_endpoint_count: result.eligible_endpoint_count,
+            resolved_endpoint_id: result.resolved_endpoint_id,
+            correlation_id: Contract::Observability::Correlation.resolve,
+          )
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/recipient_readiness/identity_facts.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module RecipientReadiness
+      # Bounded identity facts for readiness. Schema reflection for phone
+      # support stays here until Identity ships canonical phone fields.
+      IdentityFacts = Data.define(
+        :email_supported,
+        :email_present,
+        :email_validated,
+        :phone_supported,
+        :phone_present,
+        :phone_number_validated,
+      ) do
+        def self.for_user(user)
+          phone_supported = phone_capability_exposed?(user)
+
+          new(
+            email_supported: true,
+            email_present: user.email.to_s.strip.present?,
+            email_validated: !!user.email_validated,
+            phone_supported:,
+            phone_present: phone_supported && phone_value_present?(user),
+            phone_number_validated: phone_supported && !!read_phone_validated(user),
+          ).freeze
+        end
+
+        def self.phone_capability_exposed?(user)
+          return false if user.nil?
+
+          columns = user.class.column_names
+          columns.include?("phone_number") && columns.include?("phone_number_validated")
+        end
+        private_class_method :phone_capability_exposed?
+
+        def self.phone_value_present?(user)
+          value = user.public_send(:phone_number)
+          value.to_s.strip.present?
+        rescue NoMethodError
+          false
+        end
+        private_class_method :phone_value_present?
+
+        def self.read_phone_validated(user)
+          user.public_send(:phone_number_validated)
+        rescue NoMethodError
+          false
+        end
+        private_class_method :read_phone_validated
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/recipient_readiness/reason_codes.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module RecipientReadiness
+      module ReasonCodes
+        PLATFORM_DISABLED = "platform_disabled"
+        PLATFORM_UNCONFIGURED = "platform_unconfigured"
+        IDENTITY_MISSING = "identity_missing"
+        IDENTITY_UNAVAILABLE = "identity_unavailable"
+        IDENTITY_UNVERIFIED = "identity_unverified"
+        ENDPOINT_MISSING = "endpoint_missing"
+        ENDPOINT_INACTIVE = "endpoint_inactive"
+        ENDPOINT_UNVERIFIED = "endpoint_unverified"
+        ENDPOINT_INVALID = "endpoint_invalid"
+        CREDENTIALS_MISSING = "credentials_missing"
+
+        ALL = [
+          PLATFORM_DISABLED,
+          PLATFORM_UNCONFIGURED,
+          IDENTITY_MISSING,
+          IDENTITY_UNAVAILABLE,
+          IDENTITY_UNVERIFIED,
+          ENDPOINT_MISSING,
+          ENDPOINT_INACTIVE,
+          ENDPOINT_UNVERIFIED,
+          ENDPOINT_INVALID,
+          CREDENTIALS_MISSING,
+        ].freeze
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/recipient_readiness/recipient_not_found_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module RecipientReadiness
+      class RecipientNotFoundError < Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/recipient_readiness/recipient_result.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module RecipientReadiness
+      RecipientResult = Data.define(
+        :recipient_id,
+        :channels,
+        :evaluated_at,
+      ) do
+        def self.build(recipient_id:, channels:, evaluated_at: Time.current)
+          frozen_channels =
+            channels.to_h do |key, result|
+              [key.to_s, result]
+            end.freeze
+
+          new(
+            recipient_id:,
+            channels: frozen_channels,
+            evaluated_at:,
+          ).freeze
+        end
+
+        def channel(key)
+          channels[key.to_s]
+        end
+
+        def ready_channel_keys
+          channels.select { |_key, result| result.ready }.keys.freeze
+        end
+
+        def recipient_ready_channel_keys
+          channels.select { |_key, result| result.recipient_ready }.keys.freeze
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/recipient_readiness/unknown_channel_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module RecipientReadiness
+      class UnknownChannelError < Error; end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    # Computed-on-demand recipient channel eligibility.
+    # No persistence, caching, or background jobs.
+    module RecipientReadiness
+      module_function
+
+      def for_channel(recipient_id:, channel_key:, platform_enabled_channels: [])
+        Evaluate.for_channel(
+          recipient_id:,
+          channel_key:,
+          platform_enabled_channels:,
+        )
+      end
+
+      def for_recipient(recipient_id:, platform_enabled_channels: [])
+        Evaluate.for_recipient(
+          recipient_id:,
+          platform_enabled_channels:,
+        )
+      end
+    end
+  end
+end