command_tower 0.13.1 → 0.15.0

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

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module CommandTower
+  module Messaging
+    module Execution
+      module Adapters
+        module Expo
+          # Narrow Expo Push HTTP client for Messaging notification push.
+          # Never logs tokens, Authorization headers, or raw bodies that may contain tokens.
+          class HttpClient
+            def initialize(configuration: nil)
+              @configuration = configuration || Configuration.new
+            end
+
+            # messages: Array of Expo message hashes (to/title/body/data).
+            # Returns { ok:, status_code:, tickets: [...] } where each ticket is
+            # { status:, id:, message:, error: } (error is Expo details.error when present).
+            def send_messages(messages)
+              # Expo Push /send accepts a JSON array of messages.
+              response = post_json("#{api_base_url}/send", Array(messages))
+              parse_send_response(response)
+            end
+
+            # ids: Array of ticket id strings.
+            # Returns { ok:, status_code:, receipts: { id => { status:, message:, error: } } }
+            def get_receipts(ids)
+              response = post_json("#{api_base_url}/getReceipts", { "ids" => Array(ids) })
+              parse_receipts_response(response)
+            end
+
+            private
+
+            def api_base_url
+              @configuration.api_base_url.to_s.sub(%r{/\z}, "")
+            end
+
+            def timeout_seconds
+              seconds = @configuration.timeout_seconds.to_i
+              seconds.positive? ? seconds : 5
+            end
+
+            def access_token
+              @configuration.access_token.to_s.strip
+            end
+
+            def post_json(url, payload)
+              uri = URI(url)
+              request = Net::HTTP::Post.new(uri)
+              request["Content-Type"] = "application/json"
+              request["Accept"] = "application/json"
+              token = access_token
+              request["Authorization"] = "Bearer #{token}" unless token.empty?
+              request.body = JSON.generate(payload)
+
+              Net::HTTP.start(
+                uri.hostname,
+                uri.port,
+                use_ssl: uri.scheme == "https",
+                open_timeout: timeout_seconds,
+                read_timeout: timeout_seconds,
+              ) do |http|
+                http.request(request)
+              end
+            end
+
+            def parse_send_response(response)
+              parsed = parse_json(response.body)
+              data = parsed.is_a?(Hash) ? parsed["data"] : nil
+              tickets =
+                if data.is_a?(Array)
+                  data.map { |ticket| normalize_ticket(ticket) }
+                else
+                  []
+                end
+
+              {
+                ok: response.is_a?(Net::HTTPSuccess),
+                status_code: response.code.to_i,
+                tickets:,
+              }
+            end
+
+            def parse_receipts_response(response)
+              parsed = parse_json(response.body)
+              data = parsed.is_a?(Hash) ? parsed["data"] : nil
+              receipts = {}
+              if data.is_a?(Hash)
+                data.each do |ticket_id, receipt|
+                  receipts[ticket_id.to_s] = normalize_receipt(receipt)
+                end
+              end
+
+              {
+                ok: response.is_a?(Net::HTTPSuccess),
+                status_code: response.code.to_i,
+                receipts:,
+              }
+            end
+
+            def normalize_ticket(ticket)
+              hash = ticket.is_a?(Hash) ? ticket : {}
+              details = hash["details"] || hash[:details]
+              error = details.is_a?(Hash) ? (details["error"] || details[:error]) : nil
+              {
+                status: (hash["status"] || hash[:status]).to_s,
+                id: (hash["id"] || hash[:id])&.to_s,
+                message: (hash["message"] || hash[:message])&.to_s,
+                error: error&.to_s,
+              }
+            end
+
+            def normalize_receipt(receipt)
+              hash = receipt.is_a?(Hash) ? receipt : {}
+              details = hash["details"] || hash[:details]
+              error = details.is_a?(Hash) ? (details["error"] || details[:error]) : nil
+              {
+                status: (hash["status"] || hash[:status]).to_s,
+                message: (hash["message"] || hash[:message])&.to_s,
+                error: error&.to_s,
+              }
+            end
+
+            def parse_json(body)
+              JSON.parse(body.to_s)
+            rescue JSON::ParserError
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -42,6 +42,13 @@ module CommandTower
             else
               { address: endpoint_id.to_s, error_code: nil }
             end
+          when "push"
+            eligible_ids = Array(@readiness_result&.eligible_endpoint_ids)
+            if eligible_ids.empty?
+              { address: nil, error_code: "recipient_missing" }
+            else
+              { address: eligible_ids.first.to_s, error_code: nil }
+            end
           else
             { address: nil, error_code: "adapter_unconfigured" }
           end

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

@@ -36,6 +36,10 @@ module CommandTower
             if Adapters::Pushover::Configuration.pushover_configured?
               return Adapters::Pushover::Adapter.new
             end
+          when "push"
+            if Adapters::Expo::Configuration.expo_configured?
+              return Adapters::Expo::Adapter.new
+            end
           end
 
           Adapters::UnconfiguredAdapter.new

data/app/services/command_tower/messaging/rendering/channel_renderer.rb

@@ -10,7 +10,8 @@ module CommandTower
         EMAIL_CHANNEL = "email"
         SMS_CHANNEL = "sms"
         PUSHOVER_CHANNEL = "pushover"
-        SUPPORTED_CHANNELS = [EMAIL_CHANNEL, SMS_CHANNEL, PUSHOVER_CHANNEL].freeze
+        PUSH_CHANNEL = "push"
+        SUPPORTED_CHANNELS = [EMAIL_CHANNEL, SMS_CHANNEL, PUSHOVER_CHANNEL, PUSH_CHANNEL].freeze
         TEMPLATE_DIR = CommandTower::Engine.root.join("app/views/command_tower/messaging/rendering")
         DEFAULT_TITLE = "Notification"
 
@@ -48,6 +49,8 @@ module CommandTower
               render_sms(address)
             when PUSHOVER_CHANNEL
               render_pushover(address)
+            when PUSH_CHANNEL
+              render_push(address)
             else
               raise RenderError.new(code: "render_failed", error_class: "UnsupportedChannel")
             end
@@ -80,7 +83,7 @@ module CommandTower
         end
 
         def render_pushover(address)
-          title = pushover_title
+          title = notification_title
           message = render_template("pushover.text.erb").to_s.strip
           raise ArgumentError, "message is required" if message.empty?
 
@@ -91,7 +94,20 @@ module CommandTower
           )
         end
 
-        def pushover_title
+        def render_push(address)
+          title = notification_title
+          body = render_template("push.text.erb").to_s.strip
+          raise ArgumentError, "body is required" if body.empty?
+
+          RenderedPushPayload.build(
+            recipient_address: address,
+            title:,
+            body:,
+            deep_link: template_locals[:deep_link],
+          )
+        end
+
+        def notification_title
           title = @communication.title.to_s.strip
           return title unless title.empty?
 
@@ -101,6 +117,8 @@ module CommandTower
           DEFAULT_TITLE
         end
 
+        alias pushover_title notification_title
+
         def render_template(filename)
           path = TEMPLATE_DIR.join(filename)
           raise Errno::ENOENT, "missing template #{filename}" unless path.file?

data/app/services/command_tower/messaging/rendering/rendered_push_payload.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Rendering
+      # Provider-neutral Expo push rendered payload. recipient_address is the opaque
+      # first eligible endpoint id for the ChannelRenderer gate — never the Expo token.
+      # Fan-out uses AdapterRequest#eligible_endpoint_ids.
+      RenderedPushPayload = Data.define(
+        :recipient_address,
+        :title,
+        :body,
+        :deep_link,
+      ) do
+        def self.build(recipient_address:, title:, body:, deep_link: nil)
+          values = [recipient_address, title, body, deep_link]
+          raise ArgumentError, "arbitrary hashes are not accepted" if values.any? { |v| v.is_a?(Hash) }
+          raise ArgumentError, "ActiveRecord objects are not accepted" if values.any? { |v| active_record_like?(v) }
+          raise ArgumentError, "raw exception objects are not accepted" if values.any? { |v| v.is_a?(Exception) }
+
+          validate_required_string!(recipient_address, "recipient_address")
+          validate_required_string!(title, "title")
+          validate_required_string!(body, "body")
+          unless deep_link.nil?
+            raise ArgumentError, "deep_link must be a String" unless deep_link.is_a?(String)
+            raise ArgumentError, "deep_link must not be blank when present" if deep_link.strip.empty?
+          end
+
+          new(
+            recipient_address:,
+            title:,
+            body:,
+            deep_link:,
+          ).freeze
+        end
+
+        def self.validate_required_string!(value, field_name)
+          raise ArgumentError, "#{field_name} is required" if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+          raise ArgumentError, "#{field_name} must be a String" unless value.is_a?(String)
+        end
+        private_class_method :validate_required_string!
+
+        def self.active_record_like?(value)
+          defined?(ActiveRecord::Base) && value.is_a?(ActiveRecord::Base)
+        end
+        private_class_method :active_record_like?
+      end
+    end
+  end
+end

data/app/services/command_tower/services/account/push/check_self_test_rate_limit.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      module Push
+        # Enforces Me push self-test rate limits via existing RateLimits::Check.
+        # Ceiling and window come from config.messaging.expo composers — not hardcoded here.
+        class CheckSelfTestRateLimit < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+
+          def call
+            expo = CommandTower.config.messaging.expo
+            limit = expo.self_test_per_user_hour
+            ttl_seconds = expo.self_test_window_seconds
+
+            result = CommandTower::Services::RateLimits::Check.call(
+              key: "me:push:self_test:user:#{user.id}",
+              ttl_seconds:,
+            )
+            if result.failure?
+              context.fail!(application_error: result.errors.first)
+              return
+            end
+
+            count = result.data[:count]
+            return if count <= limit
+
+            ttl = result.data[:ttl]
+            retry_after = ttl.positive? ? ttl : nil
+            context.fail!(
+              application_error: CommandTower::Errors::Account::PushTestRateLimitError.new(
+                retry_after_seconds: retry_after,
+              ),
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/account/push/create.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      module Push
+        class Create < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+          validate :address, is_a: String, required: true
+
+          def call
+            view = CommandTower::Messaging::Endpoints.create(
+              owner_user_id: user.id,
+              channel_key: "push",
+              address:,
+            )
+            context.safe_view = CtSupport.ensure_verified!(owner_user_id: user.id, safe_view: view)
+          rescue CommandTower::Messaging::Endpoints::Error => e
+            context.fail!(application_error: CtSupport.map_ct_exception!(e))
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/account/push/ct_support.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      module Push
+        # Shared CT Endpoints helpers for Account push capability services.
+        module CtSupport
+          module_function
+
+          def ensure_verified!(owner_user_id:, safe_view:)
+            return safe_view if safe_view.verification_state.to_s == "verified"
+
+            CommandTower::Messaging::Endpoints.mark_verified(
+              owner_user_id:,
+              endpoint_id: safe_view.id,
+            )
+          end
+
+          def map_ct_exception!(error)
+            case error
+            when CommandTower::Messaging::Endpoints::NotFoundError
+              CommandTower::Errors::Account::PushEndpointNotFoundError.new
+            when CommandTower::Messaging::Endpoints::ValidationError
+              if error.message.to_s.include?("disabled")
+                CommandTower::Errors::Account::PushCapabilityUnavailableError.new
+              else
+                CommandTower::Errors::ValidationError.new(details: { base: "Invalid push token" })
+              end
+            else
+              CommandTower::Errors::InternalError.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/account/push/destroy.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      module Push
+        class Destroy < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+          validate :endpoint_id, required: true
+
+          def call
+            context.safe_view = CommandTower::Messaging::Endpoints.revoke(
+              owner_user_id: user.id,
+              endpoint_id:,
+            )
+          rescue CommandTower::Messaging::Endpoints::Error => e
+            context.fail!(application_error: CtSupport.map_ct_exception!(e))
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/account/push/list.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      module Push
+        class List < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+
+          def call
+            views = CommandTower::Messaging::Endpoints.list(
+              owner_user_id: user.id,
+              channel_key: "push",
+            )
+            context.safe_views = views.select { |view| view.lifecycle_state.to_s == "active" }
+          rescue CommandTower::Messaging::Endpoints::Error => e
+            context.fail!(application_error: CtSupport.map_ct_exception!(e))
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/account/push/replace.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      module Push
+        class Replace < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+          validate :endpoint_id, required: true
+          validate :address, is_a: String, required: true
+
+          def call
+            view = CommandTower::Messaging::Endpoints.replace(
+              owner_user_id: user.id,
+              endpoint_id:,
+              address:,
+            )
+            context.safe_view = CtSupport.ensure_verified!(owner_user_id: user.id, safe_view: view)
+          rescue CommandTower::Messaging::Endpoints::Error => e
+            context.fail!(application_error: CtSupport.map_ct_exception!(e))
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/account/push/send_self_test.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      module Push
+        # Me self-test: Produce a host-registered push_delivery_test communication.
+        # Does not bypass Messaging; does not talk to Expo directly.
+        class SendSelfTest < CommandTower::Services::ApplicationService
+          NOTIFICATION_TYPE_KEY = "push_delivery_test"
+          TITLE = "Push notifications"
+          BODY = "This is a test notification from your account."
+
+          validate :user, is_a: User, required: true
+
+          def call
+            list_result = CommandTower::Services::Account::Push::List.call(user:)
+            unless list_result.success?
+              context.fail!(application_error: list_result.errors.first)
+              return
+            end
+
+            if Array(list_result.data[:safe_views]).empty?
+              context.fail!(application_error: CommandTower::Errors::Account::PushTestNoEndpointError.new)
+              return
+            end
+
+            rate_result = CommandTower::Services::Account::Push::CheckSelfTestRateLimit.call(user:)
+            unless rate_result.success?
+              context.fail!(application_error: rate_result.errors.first)
+              return
+            end
+
+            produce_result = CommandTower::Services::Messaging::Communications::Produce.call(
+              user:,
+              notification_type_key: NOTIFICATION_TYPE_KEY,
+              host_event_identity: "push_delivery_test/#{user.id}/#{SecureRandom.uuid}",
+              title: TITLE,
+              body: BODY,
+              metadata: {},
+              platform_enabled_channels: CommandTower::Services::Messaging::Preferences::PlatformEnabledChannels.call,
+            )
+            unless produce_result.success?
+              context.fail!(application_error: produce_result.errors.first)
+              return
+            end
+
+            context.communication_id = produce_result.data[:communication_id]
+            context.destination_plan_id = produce_result.data[:destination_plan_id]
+            context.selected_channels = produce_result.data[:selected_channels]
+            context.communication_status = produce_result.data[:communication_status]
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/me/push_product_gate.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Me
+      # Product gate for Expo push Me/Account endpoint lifecycle HTTP.
+      # Matches ChannelDetectors.configured?("push") / expo_configured?.
+      # Does not invent route constraints — callers return 503 when disabled.
+      module PushProductGate
+        module_function
+
+        def enabled?
+          CommandTower::Messaging::ChannelDetectors.configured?("push")
+        end
+      end
+    end
+  end
+end

data/app/views/command_tower/messaging/rendering/push.text.erb

@@ -0,0 +1 @@
+<%= body %>

data/app/workflows/command_tower/workflows/me/error_mapping.rb

@@ -24,12 +24,16 @@ module CommandTower
                CommandTower::Errors::Account::PushoverNotConfiguredError,
                CommandTower::Errors::Account::PushoverAlreadyConfiguredError,
                CommandTower::Errors::Account::PushoverVerificationFailedError,
+               CommandTower::Errors::Account::PushEndpointNotFoundError,
+               CommandTower::Errors::Account::PushTestNoEndpointError,
                CommandTower::Errors::ValidationError
             :unprocessable_entity
-          when CommandTower::Errors::Account::PhoneVerificationThrottledError
+          when CommandTower::Errors::Account::PhoneVerificationThrottledError,
+               CommandTower::Errors::Account::PushTestRateLimitError
             :too_many_requests
           when CommandTower::Errors::Account::SmsCapabilityUnavailableError,
-               CommandTower::Errors::Account::PushoverCapabilityUnavailableError
+               CommandTower::Errors::Account::PushoverCapabilityUnavailableError,
+               CommandTower::Errors::Account::PushCapabilityUnavailableError
             :service_unavailable
           when CommandTower::Errors::Account::PhoneVerificationSendFailedError,
                CommandTower::Errors::Account::PushoverProviderUnavailableError

data/app/workflows/command_tower/workflows/me/push/create_workflow.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Me
+      module Push
+        class CreateWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(current_user:, address:, auth_context: nil)
+            unless CommandTower::Services::Me::PushProductGate.enabled?
+              return failure(**WorkflowSupport.capability_failure)
+            end
+
+            result = CommandTower::Services::Account::Push::Create.call(
+              user: current_user,
+              address:,
+            )
+            unless result.success?
+              error = result.errors.first
+              return failure(
+                errors: result.errors,
+                http_status: CommandTower::Workflows::Me::ErrorMapping.http_status_for(error),
+              )
+            end
+
+            success(
+              payload: WorkflowSupport.serialize_view(result.data[:safe_view]),
+              http_status: :ok,
+              response_effects: WorkflowSupport.expire_header_effects(auth_context),
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/me/push/destroy_workflow.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Me
+      module Push
+        class DestroyWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(current_user:, endpoint_id:, auth_context: nil)
+            unless CommandTower::Services::Me::PushProductGate.enabled?
+              return failure(**WorkflowSupport.capability_failure)
+            end
+
+            result = CommandTower::Services::Account::Push::Destroy.call(
+              user: current_user,
+              endpoint_id:,
+            )
+            unless result.success?
+              error = result.errors.first
+              return failure(
+                errors: result.errors,
+                http_status: CommandTower::Workflows::Me::ErrorMapping.http_status_for(error),
+              )
+            end
+
+            success(
+              payload: WorkflowSupport.serialize_view(result.data[:safe_view]),
+              http_status: :ok,
+              response_effects: WorkflowSupport.expire_header_effects(auth_context),
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/me/push/index_workflow.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Me
+      module Push
+        class IndexWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(current_user:, auth_context: nil)
+            unless CommandTower::Services::Me::PushProductGate.enabled?
+              return failure(**WorkflowSupport.capability_failure)
+            end
+
+            result = CommandTower::Services::Account::Push::List.call(user: current_user)
+            unless result.success?
+              error = result.errors.first
+              return failure(
+                errors: result.errors,
+                http_status: CommandTower::Workflows::Me::ErrorMapping.http_status_for(error),
+              )
+            end
+
+            success(
+              payload: WorkflowSupport.serialize_collection(result.data[:safe_views]),
+              http_status: :ok,
+              response_effects: WorkflowSupport.expire_header_effects(auth_context),
+            )
+          end
+        end
+      end
+    end
+  end
+end