command_tower 0.4.0 → 0.10.0

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Me
+      class UpdateName < CommandTower::Services::ApplicationService
+        validate :user, is_a: User, required: true
+        validate :first_name, is_a: String, required: true
+        validate :last_name, is_a: String, required: true
+
+        def call
+          normalized_first = first_name.to_s.strip
+          normalized_last = last_name.to_s.strip
+
+          first_changed = normalized_first != user.first_name.to_s
+          last_changed = normalized_last != user.last_name.to_s
+
+          unless first_changed || last_changed
+            context.user = user
+            return
+          end
+
+          application_error = nil
+
+          ActiveRecord::Base.transaction do
+            if first_changed
+              application_error = mutate(first_name: normalized_first)
+              raise ActiveRecord::Rollback if application_error
+            end
+
+            if last_changed
+              application_error = mutate(last_name: normalized_last)
+              raise ActiveRecord::Rollback if application_error
+            end
+          end
+
+          if application_error
+            context.fail!(application_error:)
+            return
+          end
+
+          context.user = user.reload
+        end
+
+        private
+
+        # Returns an ApplicationError when the change was rejected, nil otherwise.
+        def mutate(**attribute)
+          result = CommandTower::UserAttributes::Mutate.call(user:, **attribute)
+          return nil if result.success?
+
+          details = result.invalid_argument_hash.transform_values { _1[:msg].to_s }
+          CommandTower::Errors::ValidationError.new(details:)
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/messaging/communications/produce.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Messaging
+      module Communications
+        # Shared multi-host produce adapter: resolve recipient → Messaging.accept → ServiceResult.
+        # Hosts supply platform_enabled_channels (deployment policy). Does not own catalog content
+        # or product workflows.
+        class Produce < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+          validate :notification_type_key, is_a: String, required: true
+          validate :host_event_identity, is_a: String, required: true
+          validate :title, is_a: String, required: true
+          validate :body, is_a: String, required: true
+          validate :metadata, is_a: Hash, required: false
+          validate :platform_enabled_channels, is_a: Array, required: true
+
+          def call
+            recipient_result = CommandTower::Services::Messaging::Recipients.call(user: user)
+            unless recipient_result.success?
+              context.fail!(application_error: recipient_result.errors.first)
+              return
+            end
+
+            accept_result = CommandTower::Messaging.accept(
+              recipient_id: recipient_result.data[:recipient_id],
+              notification_type_key:,
+              host_event_identity:,
+              title:,
+              body:,
+              metadata:,
+              preference_state: nil,
+              platform_enabled_channels:,
+              message_overrides: nil,
+            )
+
+            # Use communication_status — ServiceResult strips Interactor reserved :status.
+            context.communication_id = accept_result.communication_id
+            context.destination_plan_id = accept_result.destination_plan_id
+            context.recipient_id = accept_result.recipient_id
+            context.notification_type_key = accept_result.notification_type_key
+            context.host_event_identity = accept_result.host_event_identity
+            context.communication_status = accept_result.status
+            context.idempotent_replay = accept_result.idempotent_replay
+            context.inbox_item_id = accept_result.inbox_item_id
+            context.selected_channels = accept_result.selected_channels
+            context.inbox_selected = accept_result.inbox_selected
+          rescue CommandTower::Messaging::Accept::ValidationError => error
+            context.fail!(application_error: CommandTower::Errors::ValidationError.new(details: { messaging: error.message }))
+          rescue CommandTower::Messaging::Accept::UnknownTypeError,
+                 CommandTower::Messaging::Accept::InvalidPreferenceError,
+                 CommandTower::Messaging::Accept::IllegalOverrideError,
+                 CommandTower::Messaging::Accept::ImpossibleMandatoryPlanError
+            context.fail!(application_error: CommandTower::Errors::Messaging::AcceptRejectedError.new)
+          rescue CommandTower::Messaging::Accept::IdempotencyConflictError
+            context.fail!(application_error: CommandTower::Errors::Messaging::IdempotencyConflictError.new)
+          rescue CommandTower::Messaging::Accept::PersistenceError,
+                 CommandTower::Messaging::Accept::InvariantError
+            context.fail!(application_error: CommandTower::Errors::InternalError.new)
+          rescue CommandTower::Messaging::Accept::Error
+            context.fail!(application_error: CommandTower::Errors::InternalError.new)
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/messaging/communications/produce_many.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Messaging
+      module Communications
+        # Reusable multi-recipient fan-out: host supplies stable user ids; CT reloads
+        # User and calls single-user Produce per recipient. No audience queries here.
+        class ProduceMany < CommandTower::Services::ApplicationService
+          SYNC_MAX = 25
+          FAILURE_DETAIL_CAP = 25
+          EXECUTION_MODES = %i[async sync].freeze
+
+          validate :user_ids, is_a: Array, required: true
+          validate :notification_type_key, is_a: String, required: true
+          validate :campaign_identity, is_a: String, required: true
+          validate :title, is_a: String, required: true
+          validate :body, is_a: String, required: true
+          validate :platform_enabled_channels, is_a: Array, required: true
+          validate :metadata, is_a: Hash, required: false
+          validate :execution_mode, is_one: EXECUTION_MODES, required: false, default: :async
+
+          def call
+            ids = normalize_user_ids
+            mode = normalized_execution_mode
+
+            if mode == :sync && ids.size > SYNC_MAX
+              context.fail!(
+                application_error: CommandTower::Errors::ValidationError.new(
+                  details: {
+                    execution_mode: "sync mode allows at most #{SYNC_MAX} recipients (got #{ids.size})",
+                  }
+                )
+              )
+              return
+            end
+
+            if mode == :async
+              schedule_async(ids)
+            else
+              produce_sync(ids)
+            end
+          end
+
+          private
+
+          def normalize_user_ids
+            Array(user_ids).map { |id| Integer(id) }
+          rescue ArgumentError, TypeError
+            context.fail!(
+              application_error: CommandTower::Errors::ValidationError.new(
+                details: { user_ids: "must be an array of integer user ids" }
+              )
+            )
+            []
+          end
+
+          def normalized_execution_mode
+            mode = execution_mode
+            mode = mode.to_sym if mode.is_a?(String)
+            mode = :async if mode.nil?
+            mode
+          end
+
+          def schedule_async(ids)
+            enqueued = 0
+            enqueue_failed = 0
+
+            ids.each do |user_id|
+              CommandTower::Messaging::Communications::ProduceRecipientJob.perform_later(
+                user_id,
+                recipient_job_attrs
+              )
+              enqueued += 1
+            rescue StandardError
+              enqueue_failed += 1
+            end
+
+            context.requested = ids.size
+            context.enqueued = enqueued
+            context.enqueue_failed = enqueue_failed
+            context.campaign_identity = campaign_identity
+            context.mode = :async
+          end
+
+          def produce_sync(ids)
+            accepted = 0
+            failed = 0
+            skipped = 0
+            failures = []
+
+            ids.each do |user_id|
+              user = User.find_by(id: user_id)
+              unless user
+                skipped += 1
+                push_failure(failures, user_id, "user_not_found")
+                next
+              end
+
+              result = produce_for(user)
+              if result.success?
+                accepted += 1
+              else
+                failed += 1
+                error = result.errors.first
+                push_failure(failures, user_id, error.respond_to?(:code) ? error.code : error.class.name)
+              end
+            rescue StandardError => error
+              failed += 1
+              push_failure(failures, user_id, error.class.name)
+            end
+
+            context.requested = ids.size
+            context.accepted = accepted
+            context.failed = failed
+            context.skipped = skipped
+            context.failures = failures
+            context.mode = :sync
+            context.campaign_identity = campaign_identity
+          end
+
+          def produce_for(user)
+            CommandTower::Services::Messaging::Communications::Produce.call(
+              user:,
+              notification_type_key:,
+              host_event_identity: "#{campaign_identity}/#{user.id}",
+              title:,
+              body:,
+              metadata:,
+              platform_enabled_channels:,
+            )
+          end
+
+          def recipient_job_attrs
+            {
+              "notification_type_key" => notification_type_key,
+              "campaign_identity" => campaign_identity,
+              "title" => title,
+              "body" => body,
+              "platform_enabled_channels" => platform_enabled_channels,
+              "metadata" => metadata,
+            }
+          end
+
+          def push_failure(failures, user_id, error_code)
+            return if failures.size >= FAILURE_DETAIL_CAP
+
+            failures << { user_id:, error_code: }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Messaging
+      module Inbox
+        module FailureMapping
+          private
+
+          def with_recipient
+            result = CommandTower::Services::Messaging::Recipients.call(user:)
+            return context.fail!(application_error: result.errors.first) unless result.success?
+
+            yield result.data[:recipient_id]
+          rescue CommandTower::Messaging::Inbox::InvalidBulkItemsError => error
+            context.fail!(application_error: CommandTower::Errors::ValidationError.new(details: { messaging: error.message, invalid_ids: error.invalid_ids }))
+          rescue CommandTower::Messaging::Inbox::ValidationError, CommandTower::Messaging::Contract::ValidationError => error
+            context.fail!(application_error: CommandTower::Errors::ValidationError.new(details: { messaging: error.message }))
+          rescue CommandTower::Messaging::Inbox::NotFoundError
+            context.fail!(application_error: CommandTower::Errors::NotFoundError.new)
+          rescue CommandTower::Messaging::Inbox::InvariantError, CommandTower::Messaging::Contract::NotFoundError,
+                 CommandTower::Messaging::Inbox::Error, CommandTower::Messaging::Contract::Error
+            context.fail!(application_error: CommandTower::Errors::InternalError.new)
+          end
+        end
+
+        class List < CommandTower::Services::ApplicationService
+          include FailureMapping
+          validate :user, is_a: User, required: true
+          validate :limit, is_a: Integer, required: true
+          validate :offset, is_a: Integer, required: true
+          validate :scope, is_a: String, required: false, default: "inbox"
+
+          def call
+            with_recipient do |recipient_id|
+              result = CommandTower::Messaging::Inbox.list(recipient_id:, limit:, offset:, scope:)
+              context.items = result.items.map { |item| Inbox.item(item) }
+              context.pagination = { limit: result.limit, offset: result.offset, total_count: result.total_count }
+            end
+          end
+        end
+
+        class Show < CommandTower::Services::ApplicationService
+          include FailureMapping
+          validate :user, is_a: User, required: true
+          validate :inbox_item_id, is_a: Integer, required: true
+
+          def call
+            with_recipient { |recipient_id| context.item = Inbox.detail(recipient_id:, inbox_item_id:) }
+          end
+        end
+
+        class Open < Show
+          def call
+            with_recipient do |recipient_id|
+              Inbox.detail(recipient_id:, inbox_item_id:)
+              CommandTower::Messaging::Inbox.mark_viewed(recipient_id:, inbox_item_id:)
+              context.item = Inbox.detail(recipient_id:, inbox_item_id:)
+            end
+          end
+        end
+
+        class Archive < CommandTower::Services::ApplicationService
+          include FailureMapping
+          validate :user, is_a: User, required: true
+          validate :inbox_item_id, is_a: Integer, required: true
+
+          def call
+            with_recipient { |recipient_id| context.item = Inbox.item(CommandTower::Messaging::Inbox.archive(recipient_id:, inbox_item_id:)) }
+          end
+        end
+
+        class Delete < CommandTower::Services::ApplicationService
+          include FailureMapping
+          validate :user, is_a: User, required: true
+          validate :inbox_item_id, is_a: Integer, required: true
+
+          def call
+            with_recipient { |recipient_id| CommandTower::Messaging::Inbox.delete(recipient_id:, inbox_item_id:) }
+          end
+        end
+
+        class UnreadCount < CommandTower::Services::ApplicationService
+          include FailureMapping
+          validate :user, is_a: User, required: true
+
+          def call
+            with_recipient { |recipient_id| context.count = CommandTower::Messaging::Inbox.unread_count(recipient_id:).count }
+          end
+        end
+
+        module BulkMutation
+          def call
+            with_recipient do |recipient_id|
+              result = yield(recipient_id)
+              context.bulk_result = { ids: result.ids, count: result.count, changed_count: result.changed_count }
+            end
+          end
+        end
+
+        %i[Read Unread Archive Restore Delete].each do |action|
+          operation = "bulk_#{action.to_s.downcase == "read" ? "mark_viewed" : action.to_s.downcase == "unread" ? "mark_unviewed" : action.to_s.downcase}"
+          const_set(:"Bulk#{action}", Class.new(CommandTower::Services::ApplicationService) do
+            include FailureMapping
+            include BulkMutation
+            validate :user, is_a: User, required: true
+            validate :inbox_item_ids, is_a: Array, required: true
+
+            define_method(:call) { super() { |recipient_id| CommandTower::Messaging::Inbox.public_send(operation, recipient_id:, inbox_item_ids:) } }
+          end)
+        end
+
+        class << self
+          def item(item)
+            { id: item.id, title: item.title, status: item.status, viewed_at: item.viewed_at, created_at: item.created_at, updated_at: item.updated_at }
+          end
+
+          def detail(recipient_id:, inbox_item_id:)
+            item = CommandTower::Messaging::Inbox.show(recipient_id:, inbox_item_id:)
+            communication = CommandTower::Messaging::Contract::Communications.find(
+              CommandTower::Messaging::Contract::Requests::FindCommunication.build(communication_id: item.communication_id, recipient_id:)
+            )
+            item(item).merge(body: communication.body, metadata: communication.metadata, notification_type_key: communication.notification_type_key)
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/messaging/preferences/platform_enabled_channels.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Messaging
+      module Preferences
+        # Resolves host-injected platform channel enablement without reverse
+        # dependencies. Hosts assign config.messaging.platform_enabled_channels.
+        module PlatformEnabledChannels
+          module_function
+
+          def call
+            resolver = CommandTower.config.messaging.platform_enabled_channels
+            Array(resolver.call).map(&:to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/messaging/preferences/show.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Messaging
+      module Preferences
+        class Show < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+
+          def call
+            recipient_result = CommandTower::Services::Messaging::Recipients.call(user: user)
+            unless recipient_result.success?
+              context.fail!(application_error: recipient_result.errors.first)
+              return
+            end
+
+            catalog = CommandTower::Messaging::Preferences.catalog(
+              recipient_id: recipient_result.data[:recipient_id],
+              platform_enabled_channels: PlatformEnabledChannels.call,
+            )
+
+            context.catalog = catalog
+          rescue CommandTower::Messaging::Preferences::UnknownTypeError => error
+            context.fail!(application_error: CommandTower::Errors::ValidationError.new(details: { messaging: error.message }))
+          rescue CommandTower::Messaging::Preferences::InvalidPreferenceStateError => error
+            context.fail!(application_error: CommandTower::Errors::ValidationError.new(details: { messaging: error.message }))
+          rescue CommandTower::Messaging::Preferences::StoreError
+            context.fail!(application_error: CommandTower::Errors::InternalError.new)
+          rescue CommandTower::Messaging::Preferences::Error
+            context.fail!(application_error: CommandTower::Errors::InternalError.new)
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/messaging/preferences/update.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Messaging
+      module Preferences
+        class Update < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+          validate :notification_type_key, is_a: String, required: true
+          validate :preference_state, is_a: Hash, required: true
+
+          def call
+            recipient_result = CommandTower::Services::Messaging::Recipients.call(user: user)
+            unless recipient_result.success?
+              context.fail!(application_error: recipient_result.errors.first)
+              return
+            end
+
+            notification = CommandTower::Messaging::Preferences.update(
+              recipient_id: recipient_result.data[:recipient_id],
+              notification_type_key:,
+              preference_state:,
+              platform_enabled_channels: PlatformEnabledChannels.call,
+            )
+
+            context.notification = notification
+          rescue CommandTower::Messaging::Preferences::UnknownTypeError,
+                 CommandTower::Messaging::Preferences::NotSettingsVisibleError
+            context.fail!(application_error: CommandTower::Errors::NotFoundError.new)
+          rescue CommandTower::Messaging::Preferences::InvalidPreferenceWriteError => error
+            context.fail!(application_error: CommandTower::Errors::ValidationError.new(details: { messaging: error.message }))
+          rescue CommandTower::Messaging::Preferences::InvalidPreferenceStateError => error
+            context.fail!(application_error: CommandTower::Errors::ValidationError.new(details: { messaging: error.message }))
+          rescue CommandTower::Messaging::Preferences::StoreError
+            context.fail!(application_error: CommandTower::Errors::InternalError.new)
+          rescue CommandTower::Messaging::Preferences::Error
+            context.fail!(application_error: CommandTower::Errors::InternalError.new)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Messaging
+      class Recipients < CommandTower::Services::ApplicationService
+        validate :user, is_a: User, required: true
+
+        def call
+          unless user.persisted? && user.id.present?
+            context.fail!(application_error: CommandTower::Errors::Messaging::RecipientUnresolvedError.new)
+            return
+          end
+
+          context.recipient_id = user.id
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/rate_limits/check.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module RateLimits
+      class Check < CommandTower::Services::ApplicationService
+        INCREMENT_SCRIPT = <<~LUA
+          local count = redis.call('INCR', KEYS[1])
+          if count == 1 then
+            redis.call('EXPIRE', KEYS[1], tonumber(ARGV[1]))
+          end
+          return { count, redis.call('TTL', KEYS[1]) }
+        LUA
+
+        validate :key, is_a: String, required: true
+        validate :ttl_seconds, is_a: Integer, required: true
+
+        def call
+          count, ttl = CommandTower::RedisConnection.with do |redis|
+            redis.eval(INCREMENT_SCRIPT, keys: [key], argv: [ttl_seconds])
+          end
+
+          context.count = count.to_i
+          context.ttl = ttl.to_i
+        rescue Redis::BaseError => e
+          context.fail!(application_error: CommandTower::Errors::InternalError.new(cause: e))
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/service_result.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    class ServiceResult
+      INTERACTOR_INTERNAL_KEYS = %i[error rollback].freeze
+      FAILURE_ONLY_KEYS = %i[
+        msg
+        status
+        valid_arguments
+        invalid_arguments
+        invalid_argument_hash
+        invalid_argument_keys
+        application_error
+        service_metadata
+      ].freeze
+
+      attr_reader :data, :errors, :metadata
+
+      def initialize(success:, data:, errors:, metadata:)
+        @success = success
+        @data = data
+        @errors = errors
+        @metadata = metadata
+      end
+
+      def success?
+        @success
+      end
+
+      def failure?
+        !success?
+      end
+
+      def self.success(data: {}, metadata: {})
+        new(success: true, data:, errors: [], metadata:)
+      end
+
+      def self.failure(errors:, data: {}, metadata: {})
+        new(success: false, data:, errors:, metadata:)
+      end
+
+      def self.from_interactor_context(context)
+        metadata = extract_metadata(context)
+
+        if context.success?
+          success(data: extract_success_data(context), metadata: metadata)
+        elsif context.application_error
+          failure(errors: [context.application_error], metadata: metadata)
+        elsif context.invalid_arguments
+          failure(
+            errors: [
+              CommandTower::Errors::ValidationError.new(details: context.invalid_argument_hash)
+            ],
+            metadata: metadata
+          )
+        else
+          failure(errors: [CommandTower::Errors::InternalError.new], metadata: metadata)
+        end
+      end
+
+      def self.extract_metadata(context)
+        context.service_metadata || {}
+      end
+      private_class_method :extract_metadata
+
+      def self.extract_success_data(context)
+        context.to_h.except(*INTERACTOR_INTERNAL_KEYS, *FAILURE_ONLY_KEYS)
+      end
+      private_class_method :extract_success_data
+    end
+  end
+end