command_tower 0.13.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5243f531ae8a96ca6373b331d30665a0417078f9b799ca0491c78a26231b639e
-  data.tar.gz: 6d6ed873a0a3012fd8b09b952be2b4a32652980fea5ba6871c8089ffdba71ade
+  metadata.gz: bce961e0a6770bd17a23396e3fdb5066655dbe937f91c85b00c4605802c48f7d
+  data.tar.gz: e5247dda098ad94825317ec31cfff34c1fa060aac6fcf432ca5a082f93c83e02
 SHA512:
-  metadata.gz: 94aa74a9fe97771c5b690db1fa00298dd551ba9a0a62430097a3ffac583e4be5c66198768e8262f670863533fa90d18ddc5ab89e34a64fd5967d00bbf550f93b
-  data.tar.gz: 57431bc097a11ea361fe5e56d7ef797a6c07afbd076219745a0687fb33d456e809bf693785eb7d794e0a0cf9443f414d78522dc742e8d8bd5219a508155ef41d
+  metadata.gz: dd5117447c0bf551b4b55e3a402fbda78a915c8bd0e31a2fbc10a785ef747cc9c6b7c5c8e3aa5306978872fd89910233fb67a69563a3dc1c5105fe06ce67834b
+  data.tar.gz: bb8d35c52ca0e32b44134015a81462350357fa5e678e3e3bce0daa11a3f76c2e14ff7d2e0731f8ddea812185f579df464886e01464670e68a375490d21528b03

data/app/controllers/command_tower/me/push_controller.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Me
+    class PushController < CommandTower::ApplicationController
+      include CommandTower::Auth::AuthenticationBoundary
+      include CommandTower::Auth::AuthorizationBoundary
+
+      before_action :authenticate_request!
+      before_action :authorize_request!
+
+      def index
+        result = CommandTower::Workflows::Me::Push::IndexWorkflow.call(
+          current_user: current_user,
+          auth_context: current_auth_context,
+        )
+        render_application_result(result)
+      end
+
+      def create
+        deserialized = CommandTower::Deserializers::Me::Push::TokenDeserializer.call(params)
+        return render_deserializer_errors unless deserialized.success?
+
+        result = CommandTower::Workflows::Me::Push::CreateWorkflow.call(
+          current_user: current_user,
+          address: deserialized.input.address,
+          auth_context: current_auth_context,
+        )
+        render_application_result(result)
+      end
+
+      def update
+        deserialized = CommandTower::Deserializers::Me::Push::TokenDeserializer.call(params)
+        return render_deserializer_errors unless deserialized.success?
+
+        result = CommandTower::Workflows::Me::Push::ReplaceWorkflow.call(
+          current_user: current_user,
+          endpoint_id: params[:id],
+          address: deserialized.input.address,
+          auth_context: current_auth_context,
+        )
+        render_application_result(result)
+      end
+
+      def destroy
+        result = CommandTower::Workflows::Me::Push::DestroyWorkflow.call(
+          current_user: current_user,
+          endpoint_id: params[:id],
+          auth_context: current_auth_context,
+        )
+        render_application_result(result)
+      end
+
+      private
+
+      def render_deserializer_errors
+        render_application_result(
+          CommandTower::Workflows::WorkflowResult.failure(
+            errors: [CommandTower::Errors::ValidationError.new(details: { base: "Missing or invalid push token" })],
+            http_status: :unprocessable_entity,
+          ),
+        )
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/me/push/token_deserializer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Me
+      module Push
+        class TokenDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define(:address)
+
+          EXPO_TOKEN = CommandTower::Messaging::Endpoints::Validators::Push::EXPO_TOKEN
+
+          def call(params)
+            address = extract(params, :token, :Token, :address, :Address)
+
+            if address.blank?
+              return failure(errors: { message: "missing_required_fields" })
+            end
+
+            unless address.match?(EXPO_TOKEN)
+              return failure(errors: { message: "invalid_push_token" })
+            end
+
+            success(Input.new(address:))
+          end
+
+          private
+
+          def extract(params, *keys)
+            keys.each do |key|
+              raw = params[key] || params[key.to_s]
+              next if raw.nil?
+
+              value = raw.to_s.strip
+              return value unless value.empty?
+            end
+            ""
+          end
+        end
+      end
+    end
+  end
+end

data/app/errors/command_tower/errors/account/push_capability_unavailable_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Errors
+    module Account
+      class PushCapabilityUnavailableError < CommandTower::Errors::ApplicationError
+        def code
+          "push_capability_unavailable"
+        end
+
+        def message
+          "Push notifications are currently unavailable"
+        end
+
+        def log_level
+          :warn
+        end
+      end
+    end
+  end
+end

data/app/errors/command_tower/errors/account/push_endpoint_not_found_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Errors
+    module Account
+      class PushEndpointNotFoundError < CommandTower::Errors::ApplicationError
+        def code
+          "push_endpoint_not_found"
+        end
+
+        def message
+          "Push endpoint was not found"
+        end
+
+        def log_level
+          :info
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/me/push_serializer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Me
+      class PushSerializer
+        def self.serialize(safe_view)
+          new(safe_view).serialize
+        end
+
+        def self.serialize_collection(safe_views)
+          {
+            endpoints: Array(safe_views).map { |view| serialize(view) },
+          }
+        end
+
+        def initialize(safe_view)
+          @safe_view = safe_view
+        end
+
+        def serialize
+          {
+            id: @safe_view.id,
+            channelKey: @safe_view.channel_key,
+            lifecycleState: @safe_view.lifecycle_state,
+            verificationState: @safe_view.verification_state,
+            maskedDisplayValue: @safe_view.masked_display_value,
+            verifiedAt: @safe_view.verified_at&.iso8601,
+            createdAt: @safe_view.created_at&.iso8601,
+            updatedAt: @safe_view.updated_at&.iso8601,
+            actions: actions_for(@safe_view),
+          }
+        end
+
+        private
+
+        def actions_for(view)
+          active = view.lifecycle_state.to_s == "active"
+          {
+            canReplace: active,
+            canRemove: active,
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -26,6 +26,10 @@ module CommandTower
         Execution::Adapters::Pushover::Configuration.pushover_configured?
       end
 
+      def expo_configured?
+        Execution::Adapters::Expo::Configuration.expo_configured?
+      end
+
       # Used by RecipientReadiness#platform_configured_for? (fail-closed).
       def configured?(channel_key)
         case channel_key.to_s
@@ -37,6 +41,8 @@ module CommandTower
           sms_configured?
         when "pushover"
           pushover_configured?
+        when "push"
+          expo_configured?
         else
           false
         end

data/app/services/command_tower/messaging/endpoints/validators/push.rb

@@ -7,10 +7,16 @@ module CommandTower
         module Push
           module_function
 
+          # Expo push token forms used by expo-notifications / Expo Push API.
+          EXPO_TOKEN = /\A(ExponentPushToken|ExpoPushToken)\[[^\]]+\]\z/
+
           def validate!(address)
             token = address.to_s.strip
             raise ValidationError, "push token must be present" if token.empty?
             raise ValidationError, "push token is too short" if token.length < 8
+            unless token.match?(EXPO_TOKEN)
+              raise ValidationError, "push token must be an Expo push token (ExponentPushToken[...] or ExpoPushToken[...])"
+            end
 
             Result.new(
               normalized_address: token,

data/app/services/command_tower/messaging/execution/adapter_request.rb

@@ -9,8 +9,16 @@ module CommandTower
         :channel_key,
         :attempt_id,
         :rendered,
+        :eligible_endpoint_ids,
       ) do
-        def self.build(channel_delivery_id:, communication_id:, channel_key:, attempt_id:, rendered:)
+        def self.build(
+          channel_delivery_id:,
+          communication_id:,
+          channel_key:,
+          attempt_id:,
+          rendered:,
+          eligible_endpoint_ids: []
+        )
           raise InvalidAdapterContractError, "arbitrary hashes are not accepted" if [channel_delivery_id, communication_id, channel_key, attempt_id].any? { |v| v.is_a?(Hash) }
           raise InvalidAdapterContractError, "channel_delivery_id is required" if blank?(channel_delivery_id)
           raise InvalidAdapterContractError, "communication_id is required" if blank?(communication_id)
@@ -20,11 +28,20 @@ module CommandTower
           raise InvalidAdapterContractError, "rendered is required" if rendered.nil?
           unless rendered.is_a?(Rendering::RenderedPayload) ||
               rendered.is_a?(Rendering::RenderedSmsPayload) ||
-              rendered.is_a?(Rendering::RenderedPushoverPayload)
+              rendered.is_a?(Rendering::RenderedPushoverPayload) ||
+              rendered.is_a?(Rendering::RenderedPushPayload)
             raise InvalidAdapterContractError,
-                  "rendered must be a RenderedPayload, RenderedSmsPayload, or RenderedPushoverPayload"
+                  "rendered must be a RenderedPayload, RenderedSmsPayload, RenderedPushoverPayload, or RenderedPushPayload"
           end
           raise InvalidAdapterContractError, "rendered must be frozen" unless rendered.frozen?
+          raise InvalidAdapterContractError, "eligible_endpoint_ids must be an Array" unless eligible_endpoint_ids.is_a?(Array)
+
+          ids = eligible_endpoint_ids.map do |id|
+            integer_id = Integer(id, exception: false)
+            raise InvalidAdapterContractError, "eligible_endpoint_ids must be Integers" if integer_id.nil?
+
+            integer_id
+          end
 
           new(
             channel_delivery_id:,
@@ -32,6 +49,7 @@ module CommandTower
             channel_key:,
             attempt_id:,
             rendered:,
+            eligible_endpoint_ids: ids.freeze,
           ).freeze
         end
 

data/app/services/command_tower/messaging/execution/adapters/expo/adapter.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      module Adapters
+        module Expo
+          # Execution adapter: fans out to eligible push endpoints, sends via Expo
+          # Push API, fetches receipts once for ok tickets, and marks invalid devices.
+          class Adapter
+            DEVICE_INVALID_ERRORS = %w[DeviceNotRegistered].freeze
+
+            EndpointAttempt = Struct.new(
+              :endpoint_id,
+              :token,
+              :ticket,
+              :receipt,
+              :outcome,
+              :error_code,
+              keyword_init: true,
+            )
+
+            def initialize(configuration: nil, http_client: nil, secret_reader: nil)
+              @configuration = configuration || Configuration.new
+              @http_client = http_client || HttpClient.new(configuration: @configuration)
+              @secret_reader = secret_reader || Endpoints::SecretReader
+            end
+
+            def call(request:)
+              raise ArgumentError, "request must be an AdapterRequest" unless request.is_a?(AdapterRequest)
+
+              rendered = request.rendered
+              unless rendered.is_a?(Rendering::RenderedPushPayload)
+                return AdapterResult.build(outcome: :terminal_failure, error_code: "render_failed")
+              end
+
+              unless @configuration.expo_configured?
+                return AdapterResult.build(outcome: :terminal_failure, error_code: "adapter_unconfigured")
+              end
+
+              endpoint_ids = Array(request.eligible_endpoint_ids)
+              if endpoint_ids.empty?
+                return AdapterResult.build(outcome: :terminal_failure, error_code: "recipient_missing")
+              end
+
+              delivery = Messaging::ChannelDelivery.includes(:communication).find_by(id: request.channel_delivery_id)
+              owner_user_id = delivery&.communication&.user_id
+              if owner_user_id.nil?
+                return AdapterResult.build(outcome: :terminal_failure, error_code: "recipient_missing")
+              end
+
+              attempts = build_endpoint_attempts(owner_user_id:, endpoint_ids:)
+              return attempts if attempts.is_a?(AdapterResult)
+
+              case @configuration.adapter_name
+              when "fake", "log"
+                AdapterResult.build(outcome: :success, normalized_provider_status: "accepted")
+              when "http"
+                deliver_http(attempts:, rendered:, owner_user_id:)
+              else
+                AdapterResult.build(outcome: :terminal_failure, error_code: "adapter_unconfigured")
+              end
+            rescue StandardError
+              AdapterResult.build(outcome: :retryable_failure, error_code: "expo_transient")
+            end
+
+            private
+
+            def build_endpoint_attempts(owner_user_id:, endpoint_ids:)
+              attempts = endpoint_ids.map do |endpoint_id|
+                token = @secret_reader.read!(owner_user_id:, endpoint_id:)
+                EndpointAttempt.new(endpoint_id:, token:, outcome: nil)
+              rescue Endpoints::NotFoundError, Endpoints::ValidationError
+                EndpointAttempt.new(
+                  endpoint_id:,
+                  token: nil,
+                  outcome: :terminal_failure,
+                  error_code: "recipient_missing",
+                )
+              end
+
+              if attempts.all? { |attempt| attempt.outcome == :terminal_failure }
+                return AdapterResult.build(outcome: :terminal_failure, error_code: "recipient_missing")
+              end
+
+              attempts
+            end
+
+            def deliver_http(attempts:, rendered:, owner_user_id:)
+              sendable = attempts.select { |attempt| attempt.token.present? && attempt.outcome.nil? }
+              messages = sendable.map { |attempt| expo_message(token: attempt.token, rendered:) }
+
+              send_result = @http_client.send_messages(messages)
+              unless send_result[:ok]
+                return map_http_failure(send_result[:status_code])
+              end
+
+              tickets = Array(send_result[:tickets])
+              sendable.each_with_index do |attempt, index|
+                ticket = tickets[index]
+                attempt.ticket = ticket
+                apply_ticket_outcome!(attempt)
+              end
+
+              ok_ticket_ids = sendable.filter_map { |attempt| attempt.ticket&.dig(:id) if attempt.ticket&.dig(:status) == "ok" }
+              if ok_ticket_ids.any?
+                receipts_result = @http_client.get_receipts(ok_ticket_ids)
+                if receipts_result[:ok]
+                  receipts = receipts_result[:receipts] || {}
+                  sendable.each do |attempt|
+                    ticket_id = attempt.ticket&.dig(:id)
+                    next if ticket_id.nil?
+                    next unless attempt.ticket&.dig(:status) == "ok"
+
+                    receipt = receipts[ticket_id]
+                    attempt.receipt = receipt
+                    apply_receipt_outcome!(attempt)
+                  end
+                end
+                # Missing or failed receipt fetch: ticket ok without receipt stays success (plan).
+              end
+
+              sendable.each do |attempt|
+                mark_invalid_if_needed!(owner_user_id:, attempt:)
+              end
+
+              aggregate_result(attempts)
+            end
+
+            def expo_message(token:, rendered:)
+              message = {
+                "to" => token,
+                "title" => rendered.title,
+                "body" => rendered.body,
+                "sound" => "default",
+              }
+              if rendered.deep_link.present?
+                message["data"] = { "deepLink" => rendered.deep_link }
+              end
+              message
+            end
+
+            def apply_ticket_outcome!(attempt)
+              ticket = attempt.ticket
+              if ticket.nil?
+                attempt.outcome = :retryable_failure
+                attempt.error_code = "expo_transient"
+                return
+              end
+
+              case ticket[:status]
+              when "ok"
+                attempt.outcome = :success
+              when "error"
+                if device_invalid_error?(ticket[:error])
+                  attempt.outcome = :terminal_failure
+                  attempt.error_code = "expo_device_invalid"
+                else
+                  attempt.outcome = :terminal_failure
+                  attempt.error_code = "expo_rejected"
+                end
+              else
+                attempt.outcome = :retryable_failure
+                attempt.error_code = "expo_transient"
+              end
+            end
+
+            def apply_receipt_outcome!(attempt)
+              receipt = attempt.receipt
+              return if receipt.nil? # pending / missing → keep ticket success
+
+              case receipt[:status]
+              when "ok"
+                attempt.outcome = :success
+              when "error"
+                if device_invalid_error?(receipt[:error])
+                  attempt.outcome = :terminal_failure
+                  attempt.error_code = "expo_device_invalid"
+                else
+                  attempt.outcome = :terminal_failure
+                  attempt.error_code = "expo_rejected"
+                end
+              end
+            end
+
+            def device_invalid_error?(error)
+              DEVICE_INVALID_ERRORS.include?(error.to_s)
+            end
+
+            def mark_invalid_if_needed!(owner_user_id:, attempt:)
+              return unless attempt.error_code == "expo_device_invalid"
+
+              Endpoints.mark_invalid(owner_user_id:, endpoint_id: attempt.endpoint_id)
+            rescue StandardError
+              nil
+            end
+
+            def map_http_failure(status_code)
+              if status_code.to_i >= 500 || status_code.to_i == 429
+                AdapterResult.build(outcome: :retryable_failure, error_code: "expo_transient")
+              else
+                AdapterResult.build(outcome: :terminal_failure, error_code: "expo_rejected")
+              end
+            end
+
+            def aggregate_result(attempts)
+              successes = attempts.select { |attempt| attempt.outcome == :success }
+              if successes.any?
+                first_ticket_id = successes.filter_map { |attempt| attempt.ticket&.dig(:id) }.first
+                return AdapterResult.build(
+                  outcome: :success,
+                  normalized_provider_status: "accepted",
+                  provider_message_id: first_ticket_id,
+                )
+              end
+
+              if attempts.all? { |attempt| attempt.outcome == :terminal_failure }
+                error_code = attempts.map(&:error_code).compact.first || "expo_rejected"
+                return AdapterResult.build(outcome: :terminal_failure, error_code:)
+              end
+
+              AdapterResult.build(outcome: :retryable_failure, error_code: "expo_transient")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/execution/adapters/expo/configuration.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Execution
+      module Adapters
+        module Expo
+          # Platform readiness detector for Expo Push delivery.
+          # Ready when transport adapter is fake, log, or http — disabled never counts.
+          # http does not require access_token (Expo default); Bearer is optional.
+          class Configuration
+            CONFIGURED_ADAPTERS = %w[fake log http].freeze
+
+            def self.expo_configured?
+              new.expo_configured?
+            end
+
+            def expo_configured?
+              CONFIGURED_ADAPTERS.include?(adapter_name)
+            end
+
+            def adapter_name
+              CommandTower.config.messaging.expo.adapter.to_s
+            end
+
+            def api_base_url
+              CommandTower.config.messaging.expo.api_base_url.to_s.strip
+            end
+
+            def timeout_seconds
+              CommandTower.config.messaging.expo.timeout_seconds
+            end
+
+            def access_token
+              CommandTower.config.messaging.expo.access_token.to_s.strip
+            end
+          end
+        end
+      end
+    end
+  end
+end