command_tower 0.4.0 → 0.10.0

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

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Inbox
+      class Mutator
+        # Bulk-operation ceiling. Intentionally independent from Reader::MAX_LIMIT:
+        # list page size and the number of items a recipient may mutate in one
+        # transaction are tuned separately.
+        BULK_MAX_IDS = 100
+
+        # Operations that require a live row; a soft-deleted item is not available to them.
+        LIVE_ROW_OPERATIONS = %i[mark_viewed mark_unviewed archive restore].freeze
+
+        class << self
+          def mark_viewed(recipient_id:, inbox_item_id:)
+            mutate(recipient_id:, inbox_item_id:, operation: :mark_viewed)
+          end
+
+          def mark_unviewed(recipient_id:, inbox_item_id:)
+            mutate(recipient_id:, inbox_item_id:, operation: :mark_unviewed)
+          end
+
+          def archive(recipient_id:, inbox_item_id:)
+            mutate(recipient_id:, inbox_item_id:, operation: :archive)
+          end
+
+          def restore(recipient_id:, inbox_item_id:)
+            mutate(recipient_id:, inbox_item_id:, operation: :restore)
+          end
+
+          def delete(recipient_id:, inbox_item_id:)
+            mutate(recipient_id:, inbox_item_id:, operation: :delete)
+          end
+
+          def bulk_mark_viewed(recipient_id:, inbox_item_ids:)
+            bulk_mutate(recipient_id:, inbox_item_ids:, operation: :mark_viewed)
+          end
+
+          def bulk_mark_unviewed(recipient_id:, inbox_item_ids:)
+            bulk_mutate(recipient_id:, inbox_item_ids:, operation: :mark_unviewed)
+          end
+
+          def bulk_archive(recipient_id:, inbox_item_ids:)
+            bulk_mutate(recipient_id:, inbox_item_ids:, operation: :archive)
+          end
+
+          def bulk_restore(recipient_id:, inbox_item_ids:)
+            bulk_mutate(recipient_id:, inbox_item_ids:, operation: :restore)
+          end
+
+          def bulk_delete(recipient_id:, inbox_item_ids:)
+            bulk_mutate(recipient_id:, inbox_item_ids:, operation: :delete)
+          end
+
+          private
+
+          def mutate(recipient_id:, inbox_item_id:, operation:)
+            recipient_id = require_recipient_id!(recipient_id)
+            inbox_item_id = require_inbox_item_id!(inbox_item_id)
+
+            result = nil
+            outcome = nil
+
+            ActiveRecord::Base.transaction do
+              record = Scope.find_for_recipient(
+                recipient_id:,
+                inbox_item_id:,
+                lock: true,
+              )
+              raise NotFoundError, "inbox item not found" if record.nil?
+              raise NotFoundError, "inbox item not found" unless available_for?(operation, record)
+
+              outcome = apply(operation, record)
+              record.reload
+              result = ItemResult.from_record(record)
+            end
+
+            if outcome == :changed
+              OperationLogger.lifecycle_changed(operation:, item: result)
+            end
+
+            result
+          end
+
+          # Atomic batch: every id is validated for the recipient and the operation
+          # before any row is mutated, so a batch never partially persists.
+          def bulk_mutate(recipient_id:, inbox_item_ids:, operation:)
+            recipient_id = require_recipient_id!(recipient_id)
+            requested_ids = require_inbox_item_ids!(inbox_item_ids)
+
+            ids = []
+            changed_ids = []
+
+            ActiveRecord::Base.transaction do
+              lock_all_for_recipient!(recipient_id:, requested_ids:, operation:).each do |record|
+                ids << record.id
+                changed_ids << record.id if apply(operation, record) == :changed
+              end
+            end
+
+            log_bulk_lifecycle(recipient_id:, operation:, changed_ids:)
+
+            BulkResult.build(ids:, changed_count: changed_ids.size)
+          end
+
+          def lock_all_for_recipient!(recipient_id:, requested_ids:, operation:)
+            records_by_id =
+              Scope
+                .for_recipient(recipient_id)
+                .lock
+                .where(id: requested_ids)
+                .index_by { |record| record.id.to_s }
+
+            invalid_ids = requested_ids.reject do |requested_id|
+              record = records_by_id[requested_id.to_s]
+              record && available_for?(operation, record)
+            end
+
+            if invalid_ids.any?
+              raise InvalidBulkItemsError.new(
+                "inbox items are unavailable for #{operation}",
+                invalid_ids:,
+              )
+            end
+
+            requested_ids.map { |requested_id| records_by_id.fetch(requested_id.to_s) }
+          end
+
+          # Logs post-commit, one lifecycle event per actually-changed item.
+          def log_bulk_lifecycle(recipient_id:, operation:, changed_ids:)
+            return if changed_ids.empty?
+
+            records_by_id =
+              Scope
+                .for_recipient(recipient_id)
+                .includes(:communication)
+                .where(id: changed_ids)
+                .index_by(&:id)
+
+            changed_ids.each do |changed_id|
+              record = records_by_id[changed_id]
+              next if record.nil?
+
+              OperationLogger.lifecycle_changed(
+                operation:,
+                item: ItemResult.from_record(record),
+                bulk: true,
+              )
+            end
+          end
+
+          def available_for?(operation, record)
+            return true unless LIVE_ROW_OPERATIONS.include?(operation)
+
+            !record.deleted?
+          end
+
+          def apply(operation, record)
+            case operation
+            when :mark_viewed then apply_mark_viewed(record)
+            when :mark_unviewed then apply_mark_unviewed(record)
+            when :archive then apply_archive(record)
+            when :restore then apply_restore(record)
+            when :delete then apply_delete(record)
+            else raise InvariantError, "unknown inbox operation #{operation}"
+            end
+          end
+
+          def apply_mark_viewed(record)
+            return :noop unless record.viewed_at.nil?
+
+            attrs = { viewed_at: Time.current }
+            attrs[:status] = Messaging::InboxItem::STATUS_VIEWED unless record.archived?
+            record.update!(attrs)
+            :changed
+          end
+
+          def apply_mark_unviewed(record)
+            return :noop if record.viewed_at.nil?
+
+            attrs = { viewed_at: nil }
+            attrs[:status] = Messaging::InboxItem::STATUS_CREATED unless record.archived?
+            record.update!(attrs)
+            :changed
+          end
+
+          def apply_archive(record)
+            return :noop unless record.archived_at.nil?
+
+            record.update!(
+              archived_at: Time.current,
+              status: Messaging::InboxItem::STATUS_ARCHIVED,
+            )
+            :changed
+          end
+
+          def apply_restore(record)
+            return :noop if record.archived_at.nil?
+
+            status =
+              if record.viewed_at.nil?
+                Messaging::InboxItem::STATUS_CREATED
+              else
+                Messaging::InboxItem::STATUS_VIEWED
+              end
+            record.update!(archived_at: nil, status:)
+            :changed
+          end
+
+          def apply_delete(record)
+            return :noop unless record.deleted_at.nil?
+
+            record.update!(
+              deleted_at: Time.current,
+              status: Messaging::InboxItem::STATUS_DELETED,
+            )
+            :changed
+          end
+
+          def require_recipient_id!(recipient_id)
+            raise ValidationError, "recipient_id is required" if blank?(recipient_id)
+
+            recipient_id
+          end
+
+          def require_inbox_item_id!(inbox_item_id)
+            raise ValidationError, "inbox_item_id is required" if blank?(inbox_item_id)
+
+            inbox_item_id
+          end
+
+          def require_inbox_item_ids!(inbox_item_ids)
+            raise ValidationError, "inbox_item_ids must be an array" unless inbox_item_ids.is_a?(Array)
+            raise ValidationError, "inbox_item_ids must not contain blank ids" if inbox_item_ids.any? { |id| blank?(id) }
+
+            ids = inbox_item_ids.uniq(&:to_s)
+            raise ValidationError, "inbox_item_ids is required" if ids.empty?
+            raise ValidationError, "inbox_item_ids must contain at most #{BULK_MAX_IDS} ids" if ids.size > BULK_MAX_IDS
+
+            ids
+          end
+
+          def blank?(value)
+            value.nil? || (value.respond_to?(:empty?) && value.empty?) ||
+              (value.is_a?(String) && value.strip.empty?)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Inbox
+      class NotFoundError < Error; end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Inbox
+      class OperationLogger
+        EVENT_BY_OPERATION = {
+          mark_viewed: "messaging.inbox.viewed",
+          mark_unviewed: "messaging.inbox.unviewed",
+          archive: "messaging.inbox.archived",
+          restore: "messaging.inbox.restored",
+          delete: "messaging.inbox.deleted",
+        }.freeze
+
+        class << self
+          def lifecycle_changed(operation:, item:, bulk: false)
+            event = EVENT_BY_OPERATION.fetch(operation)
+            Contract::Observability::StructuredLogger.info(
+              event:,
+              messaging_operation: "inbox",
+              operation: operation.to_s,
+              bulk:,
+              correlation_id: Contract::Observability::Correlation.resolve,
+              recipient_id: item.recipient_id,
+              inbox_item_id: item.id,
+              communication_id: item.communication_id,
+              status: item.status,
+              viewed_at: item.viewed_at&.utc&.iso8601(3),
+              archived_at: item.archived_at&.utc&.iso8601(3),
+              deleted_at: item.deleted_at&.utc&.iso8601(3),
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Inbox
+      class Reader
+        DEFAULT_LIMIT = 50
+        MAX_LIMIT = 100
+        SCOPE_INBOX = "inbox"
+        SCOPE_ARCHIVED = "archived"
+        ALLOWED_SCOPES = [SCOPE_INBOX, SCOPE_ARCHIVED].freeze
+
+        class << self
+          def list(recipient_id:, limit: DEFAULT_LIMIT, offset: 0, scope: SCOPE_INBOX)
+            recipient_id = require_recipient_id!(recipient_id)
+            limit = normalize_limit!(limit)
+            offset = normalize_offset!(offset)
+            scope = normalize_scope!(scope)
+
+            list_scope =
+              if scope == SCOPE_ARCHIVED
+                Messaging::InboxItem.archived_list
+              else
+                Messaging::InboxItem.default_list
+              end
+
+            scoped = Scope.for_recipient(recipient_id).merge(list_scope)
+            total_count = scoped.count
+            records =
+              scoped
+                .includes(:communication)
+                .order(Arel.sql("messaging_inbox_items.created_at DESC, messaging_inbox_items.id DESC"))
+                .limit(limit)
+                .offset(offset)
+                .to_a
+
+            ListResult.build(
+              items: records.map { |record| ItemResult.from_record(record) },
+              limit:,
+              offset:,
+              total_count:,
+            )
+          end
+
+          def show(recipient_id:, inbox_item_id:)
+            recipient_id = require_recipient_id!(recipient_id)
+            inbox_item_id = require_inbox_item_id!(inbox_item_id)
+
+            record = Scope.find_for_recipient(recipient_id:, inbox_item_id:)
+            raise NotFoundError, "inbox item not found" if record.nil? || record.deleted?
+
+            ItemResult.from_record(record)
+          end
+
+          def unread_count(recipient_id:)
+            recipient_id = require_recipient_id!(recipient_id)
+
+            count = Scope.for_recipient(recipient_id).merge(Messaging::InboxItem.unread).count
+            UnreadCountResult.build(recipient_id:, count:)
+          end
+
+          private
+
+          def require_recipient_id!(recipient_id)
+            raise ValidationError, "recipient_id is required" if blank?(recipient_id)
+
+            recipient_id
+          end
+
+          def require_inbox_item_id!(inbox_item_id)
+            raise ValidationError, "inbox_item_id is required" if blank?(inbox_item_id)
+
+            inbox_item_id
+          end
+
+          def normalize_limit!(limit)
+            value = Integer(limit)
+            raise ValidationError, "limit must be greater than 0" if value < 1
+            raise ValidationError, "limit must be <= #{MAX_LIMIT}" if value > MAX_LIMIT
+
+            value
+          rescue ArgumentError, TypeError
+            raise ValidationError, "limit must be an integer"
+          end
+
+          def normalize_offset!(offset)
+            value = Integer(offset)
+            raise ValidationError, "offset must be >= 0" if value.negative?
+
+            value
+          rescue ArgumentError, TypeError
+            raise ValidationError, "offset must be an integer"
+          end
+
+          def normalize_scope!(scope)
+            value =
+              if scope.nil? || (scope.respond_to?(:empty?) && scope.empty?) ||
+                   (scope.is_a?(String) && scope.strip.empty?)
+                SCOPE_INBOX
+              else
+                scope.to_s.strip
+              end
+
+            raise ValidationError, "scope must be inbox or archived" unless ALLOWED_SCOPES.include?(value)
+
+            value
+          end
+
+          def blank?(value)
+            value.nil? || (value.respond_to?(:empty?) && value.empty?) ||
+              (value.is_a?(String) && value.strip.empty?)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Inbox
+      # Recipient-scoped InboxItem relation — never load globally then check ownership.
+      module Scope
+        module_function
+
+        def for_recipient(recipient_id)
+          Messaging::InboxItem
+            .joins(:communication)
+            .where(messaging_communications: { user_id: recipient_id })
+        end
+
+        def find_for_recipient(recipient_id:, inbox_item_id:, lock: false)
+          relation = for_recipient(recipient_id)
+          relation = relation.lock if lock
+          relation.find_by(id: inbox_item_id)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Inbox
+      UnreadCountResult = Data.define(:recipient_id, :count) do
+        def self.build(recipient_id:, count:)
+          new(
+            recipient_id:,
+            count: Integer(count),
+          ).freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Inbox
+      class ValidationError < Error; end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Inbox
+      module_function
+
+      def list(recipient_id:, limit: Reader::DEFAULT_LIMIT, offset: 0, scope: Reader::SCOPE_INBOX)
+        Reader.list(recipient_id:, limit:, offset:, scope:)
+      end
+
+      def show(recipient_id:, inbox_item_id:)
+        Reader.show(recipient_id:, inbox_item_id:)
+      end
+
+      def unread_count(recipient_id:)
+        Reader.unread_count(recipient_id:)
+      end
+
+      def mark_viewed(recipient_id:, inbox_item_id:)
+        Mutator.mark_viewed(recipient_id:, inbox_item_id:)
+      end
+
+      def mark_unviewed(recipient_id:, inbox_item_id:)
+        Mutator.mark_unviewed(recipient_id:, inbox_item_id:)
+      end
+
+      def archive(recipient_id:, inbox_item_id:)
+        Mutator.archive(recipient_id:, inbox_item_id:)
+      end
+
+      def restore(recipient_id:, inbox_item_id:)
+        Mutator.restore(recipient_id:, inbox_item_id:)
+      end
+
+      def delete(recipient_id:, inbox_item_id:)
+        Mutator.delete(recipient_id:, inbox_item_id:)
+      end
+
+      def bulk_mark_viewed(recipient_id:, inbox_item_ids:)
+        Mutator.bulk_mark_viewed(recipient_id:, inbox_item_ids:)
+      end
+
+      def bulk_mark_unviewed(recipient_id:, inbox_item_ids:)
+        Mutator.bulk_mark_unviewed(recipient_id:, inbox_item_ids:)
+      end
+
+      def bulk_archive(recipient_id:, inbox_item_ids:)
+        Mutator.bulk_archive(recipient_id:, inbox_item_ids:)
+      end
+
+      def bulk_restore(recipient_id:, inbox_item_ids:)
+        Mutator.bulk_restore(recipient_id:, inbox_item_ids:)
+      end
+
+      def bulk_delete(recipient_id:, inbox_item_ids:)
+        Mutator.bulk_delete(recipient_id:, inbox_item_ids:)
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/notification_types/catalog_category.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module NotificationTypes
+      # Immutable grouped catalog entry returned by Registry#catalog.
+      CatalogCategory = Data.define(:key, :label, :order, :declarations) do
+        def self.build(key:, label:, order:, declarations:)
+          new(
+            key: key.to_s,
+            label: label.to_s,
+            order:,
+            declarations: Array(declarations).freeze,
+          ).freeze
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/notification_types/declaration.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module NotificationTypes
+      Declaration = Data.define(
+        :key,
+        :allowed_channels,
+        :default_channels,
+        :inbox_available,
+        :user_configurable,
+        :mandatory,
+        :default_preference_state,
+        :label,
+        :category_key,
+        :category_label,
+        :category_order,
+        :type_order,
+        :settings_visible,
+        :description,
+        :priority,
+        :retention,
+        :delivery_status_visible,
+        :host_ownership,
+      ) do
+        def self.build(
+          key:,
+          allowed_channels:,
+          default_channels:,
+          inbox_available:,
+          user_configurable:,
+          mandatory:,
+          default_preference_state:,
+          label:,
+          category_key:,
+          category_label:,
+          category_order:,
+          type_order:,
+          settings_visible: true,
+          description: nil,
+          priority: nil,
+          retention: nil,
+          delivery_status_visible: nil,
+          host_ownership: nil
+        )
+          new(
+            key: key.nil? ? nil : key.to_s,
+            allowed_channels: freeze_channel_list(allowed_channels),
+            default_channels: freeze_channel_list(default_channels),
+            inbox_available: !!inbox_available,
+            user_configurable: !!user_configurable,
+            mandatory: !!mandatory,
+            default_preference_state: freeze_preference_state(default_preference_state),
+            label: label.nil? ? nil : label.to_s,
+            category_key: category_key.nil? ? nil : category_key.to_s,
+            category_label: category_label.nil? ? nil : category_label.to_s,
+            category_order:,
+            type_order:,
+            settings_visible: !!settings_visible,
+            description:,
+            priority:,
+            retention:,
+            delivery_status_visible:,
+            host_ownership:,
+          ).freeze
+        end
+
+        def self.freeze_channel_list(channels)
+          return nil if channels.nil?
+
+          Array(channels).map { |channel| channel.to_s }.freeze
+        end
+        private_class_method :freeze_channel_list
+
+        def self.freeze_preference_state(state)
+          return nil if state.nil?
+
+          hash = state.to_h.transform_keys(&:to_s)
+          channels = hash["channels"]
+          frozen_channels =
+            if channels.nil?
+              nil
+            else
+              channels.to_h.transform_keys(&:to_s).transform_values { |value| !!value }.freeze
+            end
+
+          {
+            "channels" => frozen_channels,
+            "inbox" => hash.key?("inbox") ? !!hash["inbox"] : nil,
+          }.freeze
+        end
+        private_class_method :freeze_preference_state
+      end
+    end
+  end
+end