command_tower 0.3.1 → 0.10.0

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

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "erb"
+require "cgi"
+
+module CommandTower
+  module Messaging
+    module Rendering
+      class ChannelRenderer
+        EMAIL_CHANNEL = "email"
+        SMS_CHANNEL = "sms"
+        PUSHOVER_CHANNEL = "pushover"
+        SUPPORTED_CHANNELS = [EMAIL_CHANNEL, SMS_CHANNEL, PUSHOVER_CHANNEL].freeze
+        TEMPLATE_DIR = CommandTower::Engine.root.join("app/views/command_tower/messaging/rendering")
+        DEFAULT_TITLE = "Notification"
+
+        def self.render(communication:, channel_key:, recipient_address:)
+          new(
+            communication:,
+            channel_key:,
+            recipient_address:,
+          ).render
+        end
+
+        def self.supported_channel?(channel_key)
+          SUPPORTED_CHANNELS.include?(channel_key.to_s)
+        end
+
+        def initialize(communication:, channel_key:, recipient_address:)
+          @communication = communication
+          @channel_key = channel_key.to_s
+          @recipient_address = recipient_address
+        end
+
+        def render
+          address = @recipient_address.to_s.strip
+          raise RenderError.new(code: "recipient_missing") if address.empty?
+
+          unless self.class.supported_channel?(@channel_key)
+            raise RenderError.new(code: "render_failed", error_class: "UnsupportedChannel")
+          end
+
+          begin
+            case @channel_key
+            when EMAIL_CHANNEL
+              render_email(address)
+            when SMS_CHANNEL
+              render_sms(address)
+            when PUSHOVER_CHANNEL
+              render_pushover(address)
+            else
+              raise RenderError.new(code: "render_failed", error_class: "UnsupportedChannel")
+            end
+          rescue RenderError
+            raise
+          rescue StandardError => error
+            raise RenderError.new(code: "render_failed", error_class: error.class.name)
+          end
+        end
+
+        private
+
+        def render_email(address)
+          RenderedPayload.build(
+            recipient_address: address,
+            subject: @communication.title.to_s,
+            text_body: render_template("email.text.erb"),
+            html_body: render_template("email.html.erb"),
+          )
+        end
+
+        def render_sms(address)
+          body = render_template("sms.text.erb").to_s.strip
+          raise ArgumentError, "body is required" if body.empty?
+
+          RenderedSmsPayload.build(
+            recipient_address: address,
+            body:,
+          )
+        end
+
+        def render_pushover(address)
+          title = pushover_title
+          message = render_template("pushover.text.erb").to_s.strip
+          raise ArgumentError, "message is required" if message.empty?
+
+          RenderedPushoverPayload.build(
+            recipient_address: address,
+            title:,
+            message:,
+          )
+        end
+
+        def pushover_title
+          title = @communication.title.to_s.strip
+          return title unless title.empty?
+
+          body = @communication.body.to_s.strip
+          return body[0, 50] unless body.empty?
+
+          DEFAULT_TITLE
+        end
+
+        def render_template(filename)
+          path = TEMPLATE_DIR.join(filename)
+          raise Errno::ENOENT, "missing template #{filename}" unless path.file?
+
+          template = ERB.new(path.read, trim_mode: "-")
+          template.result_with_hash(template_locals)
+        end
+
+        def template_locals
+          metadata = @communication.metadata
+          deep_link = metadata.is_a?(Hash) ? metadata["deep_link"] || metadata[:deep_link] : nil
+          deep_link = deep_link.to_s if deep_link
+
+          {
+            title: @communication.title.to_s,
+            body: @communication.body.to_s,
+            deep_link: deep_link.presence,
+            h: ->(value) { CGI.escapeHTML(value.to_s) },
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Rendering
+      class RenderError < StandardError
+        CODES = %w[recipient_missing render_failed].freeze
+
+        attr_reader :code, :error_class
+
+        def initialize(code:, error_class: nil)
+          normalized = code.to_s
+          unless CODES.include?(normalized)
+            raise ArgumentError, "unsupported render error code: #{code.inspect}"
+          end
+
+          @code = normalized
+          @error_class = error_class.nil? ? nil : error_class.to_s
+          super(normalized)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Rendering
+      RenderedPayload = Data.define(
+        :recipient_address,
+        :subject,
+        :text_body,
+        :html_body,
+      ) do
+        def self.build(recipient_address:, subject:, text_body:, html_body:)
+          values = [recipient_address, subject, text_body, html_body]
+          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!(subject, "subject")
+          validate_required_string!(text_body, "text_body")
+          validate_required_string!(html_body, "html_body")
+
+          new(
+            recipient_address:,
+            subject:,
+            text_body:,
+            html_body:,
+          ).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/messaging/rendering/rendered_pushover_payload.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Rendering
+      # Provider-neutral Pushover rendered payload. recipient_address is the opaque
+      # endpoint id resolved by RecipientReadiness — never credentials.
+      RenderedPushoverPayload = Data.define(
+        :recipient_address,
+        :title,
+        :message,
+      ) do
+        def self.build(recipient_address:, title:, message:)
+          values = [recipient_address, title, message]
+          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!(message, "message")
+
+          new(
+            recipient_address:,
+            title:,
+            message:,
+          ).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/messaging/rendering/rendered_sms_payload.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Rendering
+      # Provider-neutral SMS rendered payload. Recipient is resolved separately at
+      # execution and included here for the adapter request contract (same as email).
+      RenderedSmsPayload = Data.define(
+        :recipient_address,
+        :body,
+      ) do
+        def self.build(recipient_address:, body:)
+          values = [recipient_address, body]
+          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!(body, "body")
+
+          new(
+            recipient_address:,
+            body:,
+          ).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/messaging.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module_function
+
+    def accept(
+      recipient_id:,
+      notification_type_key:,
+      host_event_identity:,
+      title:,
+      body:,
+      metadata: nil,
+      preference_state: nil,
+      platform_enabled_channels:,
+      message_overrides: nil
+    )
+      Accept::Coordinator.call(
+        recipient_id:,
+        notification_type_key:,
+        host_event_identity:,
+        title:,
+        body:,
+        metadata:,
+        preference_state:,
+        platform_enabled_channels:,
+        message_overrides:,
+      )
+    end
+
+    def inbox
+      Inbox
+    end
+  end
+end

data/app/services/command_tower/secrets/cleanse.rb

@@ -1,14 +1,28 @@
 # frozen_string_literal: true
 
 module CommandTower::Secrets
-  class Cleanse < CommandTower::ServiceBase
-    validate :user, is_a: User, required: true
-    validate :reason, is_one: ALLOWED_SECRET_REASONS, required: true
+  # Drops every outstanding secret a user holds for one reason.
+  class Cleanse
+    include CommandTower::ServiceLogging
+
+    def self.call(user:, reason:)
+      new(user:, reason:).call
+    end
+
+    def initialize(user:, reason:)
+      @user = user
+      @reason = reason
+    end
 
     def call
-      secrets = UserSecret.where(user:, reason:)
-      count = secrets.delete_all
+      count = UserSecret.where(user:, reason:).delete_all
       log_info("Cleansed #{count} #{reason} secret(s) from the store for user [#{user.id}]")
+
+      count
     end
+
+    private
+
+    attr_reader :user, :reason
   end
 end

data/app/services/command_tower/secrets/generate.rb

@@ -1,18 +1,51 @@
 # frozen_string_literal: true
 
 module CommandTower::Secrets
-  class Generate < CommandTower::ServiceBase
+  # Issues a single-purpose user secret (email verification, password reset,
+  # phone verification). Called from capability services, so it stays a plain
+  # domain object with a narrow outcome.
+  class Generate
+    include CommandTower::ServiceLogging
+
     MAX_RETRY = 10
+    EXHAUSTED_MSG = "Failed to generate Secret. Cannot Continue"
+
+    class Issued
+      attr_reader :record, :secret, :msg
+
+      def self.success(record:)
+        new(success: true, record:, secret: record.secret)
+      end
+
+      def self.failure(msg:)
+        new(success: false, msg:)
+      end
+
+      def initialize(success:, record: nil, secret: nil, msg: nil)
+        @success = success
+        @record = record
+        @secret = secret
+        @msg = msg
+      end
+
+      def success? = @success
 
-    validate :user, is_a: User, required: true
-    validate :secret_length, is_a: Integer, gte: 4, lte: 64, required: true
-    validate :reason, is_one: ALLOWED_SECRET_REASONS, required: true
-    validate :type, is_one: ALLOWED_SECRET_TYPES, default: DEFAULT_SECRET_TYPE
-    validate :extra, is_a: String, length: true, lt: 256
-    validate :cleanse, is_one: [true, false], default: false
-    at_least_one(:death, required: true) do
-      validate :death_time, is_a: ActiveSupport::Duration, gte: 10.seconds
-      validate :use_count_max, is_a: Integer, gte: 1
+      def failure? = !@success
+    end
+
+    def self.call(**kwargs)
+      new(**kwargs).call
+    end
+
+    def initialize(user:, secret_length:, reason:, type: DEFAULT_SECRET_TYPE, extra: nil, cleanse: false, death_time: nil, use_count_max: nil)
+      @user = user
+      @secret_length = secret_length
+      @reason = reason
+      @type = type || DEFAULT_SECRET_TYPE
+      @extra = extra
+      @cleanse = !!cleanse
+      @death_time = death_time
+      @use_count_max = use_count_max
     end
 
     def call
@@ -22,30 +55,17 @@ module CommandTower::Secrets
       end
 
       @attempts ||= 1
-      record = UserSecret.create!(**db_params)
 
-      context.record = record
-      context.secret = record.secret
-    rescue ActiveRecord::RecordNotUnique => e
+      Issued.success(record: UserSecret.create!(**db_params))
+    rescue ActiveRecord::RecordNotUnique
       if @attempts < MAX_RETRY
         @attempts += 1
         log_warn("Duplicate Secret was generated. Attempting to retry: #{@attempts} of #{MAX_RETRY}")
         retry
-      else
-        log_error("Duplicate Secret was generated. Exhausted Max attempts of #{MAX_RETRY}.")
-        context.fail!(msg: "Failed to generate Secret. Cannot Continue")
       end
-    end
 
-    def db_params
-      {
-        death_time: death_time&.from_now,
-        use_count_max:,
-        extra:,
-        reason:,
-        secret: generate_secret,
-        user:,
-      }.compact
+      log_error("Duplicate Secret was generated. Exhausted Max attempts of #{MAX_RETRY}.")
+      Issued.failure(msg: EXHAUSTED_MSG)
     end
 
     def generate_secret
@@ -58,5 +78,20 @@ module CommandTower::Secrets
         SecureRandom.public_send(type)
       end
     end
+
+    private
+
+    attr_reader :user, :secret_length, :reason, :type, :extra, :cleanse, :death_time, :use_count_max
+
+    def db_params
+      {
+        death_time: death_time&.from_now,
+        use_count_max:,
+        extra:,
+        reason:,
+        secret: generate_secret,
+        user:,
+      }.compact
+    end
   end
 end

data/app/services/command_tower/secrets/verify.rb

@@ -1,27 +1,61 @@
 # frozen_string_literal: true
 
 module CommandTower::Secrets
-  class Verify < CommandTower::ServiceBase
-    validate :secret, is_a: String, required: true, sensitive: true
-    validate :reason, is_one: ALLOWED_SECRET_REASONS, required: true
-    validate :access_count, is_one: [true, false], default: false
+  # Redeems a previously issued user secret. Called from capability services, so
+  # it stays a plain domain object with a narrow outcome.
+  class Verify
+    NOT_FOUND_MSG = "Secret not found"
+
+    class Redemption
+      attr_reader :user, :record, :msg
+
+      def self.success(user:, record:)
+        new(success: true, user:, record:)
+      end
+
+      def self.failure(record:, msg:)
+        new(success: false, record:, msg:)
+      end
+
+      def initialize(success:, user: nil, record: nil, msg: nil)
+        @success = success
+        @user = user
+        @record = record
+        @msg = msg
+      end
+
+      def success? = @success
+
+      def failure? = !@success
+    end
+
+    def self.call(secret:, reason:, access_count: false)
+      new(secret:, reason:, access_count:).call
+    end
+
+    def initialize(secret:, reason:, access_count: false)
+      @secret = secret
+      @reason = reason
+      @access_count = access_count
+    end
 
     def call
       record = UserSecret.find_record(secret:, reason:, access_count:)
 
-      if record[:found] == false
-        context.fail!(record:, msg: "Secret not found")
-      end
+      return Redemption.failure(record:, msg: NOT_FOUND_MSG) if record[:found] == false
 
       if record[:valid] == false
-        if CommandTower.config.delete_secret_after_invalid
-          record[:record].destroy
-        end
+        reason_text = record[:record].invalid_reason.join(" ")
+        record[:record].destroy if CommandTower.config.delete_secret_after_invalid
 
-        context.fail!(record:, msg: "Secret is invalid. #{record[:record].invalid_reason.join(" ")}")
+        return Redemption.failure(record:, msg: "Secret is invalid. #{reason_text}")
       end
 
-      context.user = record[:user]
+      Redemption.success(user: record[:user], record:)
     end
+
+    private
+
+    attr_reader :secret, :reason, :access_count
   end
 end

data/app/services/command_tower/secrets.rb

@@ -3,7 +3,9 @@
 module CommandTower::Secrets
   ALLOWED_SECRET_REASONS = [
     EMAIL_VERIFICIATION = :email_verification,
+    PASSWORD_RESET = :password_reset,
     SSO = :sso,
+    PHONE_VERIFICATION = :phone_verification,
   ]
 
   ALLOWED_SECRET_TYPES = [

data/app/services/command_tower/services/account/clear_phone.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      # Clears the user's phone number. Idempotent when already blank.
+      class ClearPhone < CommandTower::Services::ApplicationService
+        validate :user, is_a: User, required: true
+
+        def call
+          if user.phone_number.to_s.strip.blank?
+            context.user = user
+            return
+          end
+
+          user.phone_number = nil
+          user.phone_number_validated = false
+          user.save!
+
+          context.user = user
+        end
+      end
+    end
+  end
+end