command_tower 0.13.1 → 0.14.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/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/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,14 @@ module CommandTower
                CommandTower::Errors::Account::PushoverNotConfiguredError,
                CommandTower::Errors::Account::PushoverAlreadyConfiguredError,
                CommandTower::Errors::Account::PushoverVerificationFailedError,
+               CommandTower::Errors::Account::PushEndpointNotFoundError,
                CommandTower::Errors::ValidationError
             :unprocessable_entity
           when CommandTower::Errors::Account::PhoneVerificationThrottledError
             :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

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Me
+      module Push
+        class ReplaceWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(current_user:, endpoint_id:, address:, auth_context: nil)
+            unless CommandTower::Services::Me::PushProductGate.enabled?
+              return failure(**WorkflowSupport.capability_failure)
+            end
+
+            result = CommandTower::Services::Account::Push::Replace.call(
+              user: current_user,
+              endpoint_id:,
+              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/workflow_support.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Me
+      module Push
+        module WorkflowSupport
+          module_function
+
+          def capability_failure
+            error = CommandTower::Errors::Account::PushCapabilityUnavailableError.new
+            {
+              errors: [error],
+              http_status: CommandTower::Workflows::Me::ErrorMapping.http_status_for(error),
+            }
+          end
+
+          def expire_header_effects(auth_context)
+            return if auth_context.nil?
+
+            { set_expire_header: auth_context.token_expires_at }
+          end
+
+          def serialize_view(safe_view)
+            CommandTower::Serializers::Me::PushSerializer.serialize(safe_view)
+          end
+
+          def serialize_collection(safe_views)
+            CommandTower::Serializers::Me::PushSerializer.serialize_collection(safe_views)
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/messaging/execution/deliver_workflow.rb

@@ -114,6 +114,7 @@ module CommandTower
                 channel_key: delivery.channel_key,
                 attempt_id: attempt.id,
                 rendered:,
+                eligible_endpoint_ids: Array(readiness.eligible_endpoint_ids),
               )
               adapter = CommandTower::Messaging::Execution::SelectAdapter.call(delivery:, executor:)
               CommandTower::Messaging::Execution::OperationLogger.adapter_started(

data/config/routes.rb

@@ -100,6 +100,15 @@ CommandTower::Engine.routes.draw do
     put "pushover", to: "pushover#update"
     delete "pushover", to: "pushover#destroy"
     post "pushover/verification", to: "pushover/verifications#create"
+
+    # Expo push lifecycle always drawn (no route constraints).
+    # Product readiness is workflow-gated as 503 push_capability_unavailable.
+    # Collection JSON (multi-active). No verification POST — create/replace mark_verified.
+    get "push", to: "push#index"
+    post "push", to: "push#create"
+    patch "push/:id", to: "push#update"
+    put "push/:id", to: "push#update"
+    delete "push/:id", to: "push#destroy"
   end
 
   namespace :admin do