command_tower 0.3.1 → 0.10.0

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

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      class Evaluator
+        def self.call(...)
+          new(...).call
+        end
+
+        def initialize(
+          notification_type_key:,
+          recipient_id:,
+          preference_state:,
+          platform_enabled_channels:
+        )
+          @notification_type_key = notification_type_key.to_s
+          @recipient_id = recipient_id
+          @raw_preference_state = preference_state
+          @platform_enabled_channels = Array(platform_enabled_channels).map(&:to_s).freeze
+        end
+
+        def call
+          declaration = lookup_declaration!
+          defaults = PreferenceState.from_declaration_default(declaration.default_preference_state)
+          recipient_override = PreferenceState.normalize(@raw_preference_state)
+
+          effective =
+            if declaration.user_configurable && recipient_override
+              recipient_override.merge_over(defaults)
+            else
+              defaults
+            end
+
+          permitted = []
+          suppressed = []
+
+          declaration.allowed_channels.each do |channel|
+            if !@platform_enabled_channels.include?(channel)
+              suppressed << SuppressedDestination.build(
+                destination: channel,
+                reason_class: ReasonClasses::SKIPPED_BY_POLICY,
+              )
+              next
+            end
+
+            if declaration.user_configurable && !effective.channel_enabled?(channel, default: true)
+              suppressed << SuppressedDestination.build(
+                destination: channel,
+                reason_class: ReasonClasses::SUPPRESSED_BY_PREFERENCE,
+              )
+              next
+            end
+
+            # Not user-configurable: preference opt-outs ignored; still require default enablement
+            if !declaration.user_configurable && !effective.channel_enabled?(channel, default: true)
+              suppressed << SuppressedDestination.build(
+                destination: channel,
+                reason_class: ReasonClasses::SKIPPED_BY_POLICY,
+              )
+              next
+            end
+
+            permitted << channel
+          end
+
+          extras = effective.channels.keys - declaration.allowed_channels
+          extras.each do |channel|
+            suppressed << SuppressedDestination.build(
+              destination: channel,
+              reason_class: ReasonClasses::SKIPPED_BY_POLICY,
+            )
+          end
+
+          inbox_permitted, inbox_suppressed = evaluate_inbox(declaration, effective)
+          suppressed.concat(inbox_suppressed)
+
+          mandatory_enforced = false
+          if declaration.mandatory
+            permitted, suppressed, inbox_permitted, mandatory_enforced =
+              enforce_mandatory(
+                declaration:,
+                defaults:,
+                permitted:,
+                suppressed:,
+                inbox_permitted:,
+              )
+          end
+
+          EvaluationResult.build(
+            notification_type_key: @notification_type_key,
+            recipient_id: @recipient_id,
+            permitted_channels: permitted.uniq,
+            inbox_permitted:,
+            suppressed_destinations: suppressed,
+            mandatory: declaration.mandatory,
+            mandatory_enforced:,
+            stored_override_present: false,
+            effective_preference_state: effective.to_raw_hash,
+          )
+        end
+
+        private
+
+        def lookup_declaration!
+          NotificationTypes.lookup(@notification_type_key)
+        rescue NotificationTypes::NotFoundError
+          raise UnknownTypeError, "notification type not registered: #{@notification_type_key}"
+        end
+
+        def evaluate_inbox(declaration, effective)
+          unless declaration.inbox_available
+            return [false, []]
+          end
+
+          enabled =
+            if effective.inbox.nil?
+              true
+            else
+              effective.inbox
+            end
+
+          if declaration.user_configurable && !enabled
+            return [
+              false,
+              [
+                SuppressedDestination.build(
+                  destination: :inbox,
+                  reason_class: ReasonClasses::SUPPRESSED_BY_PREFERENCE,
+                ),
+              ],
+            ]
+          end
+
+          if !declaration.user_configurable && !enabled
+            return [
+              false,
+              [
+                SuppressedDestination.build(
+                  destination: :inbox,
+                  reason_class: ReasonClasses::SKIPPED_BY_POLICY,
+                ),
+              ],
+            ]
+          end
+
+          [true, []]
+        end
+
+        def enforce_mandatory(declaration:, defaults:, permitted:, suppressed:, inbox_permitted:)
+          required_channels = declaration.default_channels & declaration.allowed_channels
+          required_inbox = declaration.inbox_available && defaults.inbox != false
+
+          enforced = false
+          permitted = permitted.dup
+          suppressed = suppressed.reject do |item|
+            next false unless item.reason_class == ReasonClasses::SUPPRESSED_BY_PREFERENCE
+
+            if item.destination == :inbox
+              next false unless required_inbox
+
+              enforced = true
+              true
+            elsif required_channels.include?(item.destination)
+              enforced = true
+              true
+            else
+              false
+            end
+          end
+
+          required_channels.each do |channel|
+            next if permitted.include?(channel)
+            next unless @platform_enabled_channels.include?(channel)
+
+            permitted << channel
+            enforced = true
+            suppressed.reject! do |item|
+              item.destination == channel && item.reason_class == ReasonClasses::SUPPRESSED_BY_PREFERENCE
+            end
+          end
+
+          if required_inbox && !inbox_permitted
+            inbox_permitted = true
+            enforced = true
+            suppressed.reject! { |item| item.destination == :inbox }
+          end
+
+          [permitted, suppressed, inbox_permitted, enforced]
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      class InvalidPreferenceWriteError < Error
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      class NotSettingsVisibleError < Error
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      PreferenceState = Data.define(:channels, :inbox) do
+        def self.normalize(raw)
+          return nil if raw.nil?
+
+          unless raw.respond_to?(:to_h)
+            raise InvalidPreferenceStateError, "preference_state must be a hash-like object"
+          end
+
+          hash = raw.to_h.transform_keys(&:to_s)
+
+          if hash.empty?
+            return nil
+          end
+
+          channels_raw = hash["channels"]
+          channels =
+            if channels_raw.nil?
+              {}.freeze
+            else
+              unless channels_raw.respond_to?(:to_h)
+                raise InvalidPreferenceStateError, "preference_state channels must be a hash-like object"
+              end
+
+              channels_raw.to_h.transform_keys(&:to_s).transform_values { |value| !!value }.freeze
+            end
+
+          inbox = hash.key?("inbox") ? !!hash["inbox"] : nil
+
+          new(channels:, inbox:).freeze
+        end
+
+        def self.from_declaration_default(default_preference_state)
+          normalize(default_preference_state) || new(channels: {}.freeze, inbox: nil).freeze
+        end
+
+        def merge_over(base)
+          merged_channels = base.channels.merge(channels)
+          merged_inbox = inbox.nil? ? base.inbox : inbox
+          self.class.new(channels: merged_channels.freeze, inbox: merged_inbox).freeze
+        end
+
+        def channel_enabled?(channel_key, default: true)
+          return default unless channels.key?(channel_key)
+
+          channels.fetch(channel_key)
+        end
+
+        def to_raw_hash
+          hash = { "channels" => channels.to_h }
+          hash["inbox"] = inbox unless inbox.nil?
+          hash
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      module ReasonClasses
+        SUPPRESSED_BY_PREFERENCE = "suppressed_by_preference"
+        SKIPPED_BY_POLICY = "skipped_by_policy"
+
+        ALL = [
+          SUPPRESSED_BY_PREFERENCE,
+          SKIPPED_BY_POLICY,
+        ].freeze
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      class Resolve
+        def self.call(...)
+          new(...).call
+        end
+
+        def initialize(
+          notification_type_key:,
+          recipient_id:,
+          platform_enabled_channels: []
+        )
+          @notification_type_key = notification_type_key.to_s
+          @recipient_id = recipient_id
+          @platform_enabled_channels = platform_enabled_channels
+        end
+
+        def call
+          stored = Store.find(
+            recipient_id: @recipient_id,
+            notification_type_key: @notification_type_key,
+          )
+          raw_override = stored&.to_raw_hash
+
+          evaluation = Evaluator.call(
+            notification_type_key: @notification_type_key,
+            recipient_id: @recipient_id,
+            preference_state: raw_override,
+            platform_enabled_channels: @platform_enabled_channels,
+          )
+
+          EvaluationResult.build(
+            notification_type_key: evaluation.notification_type_key,
+            recipient_id: evaluation.recipient_id,
+            permitted_channels: evaluation.permitted_channels,
+            inbox_permitted: evaluation.inbox_permitted,
+            suppressed_destinations: evaluation.suppressed_destinations,
+            mandatory: evaluation.mandatory,
+            mandatory_enforced: evaluation.mandatory_enforced,
+            stored_override_present: !stored.nil?,
+            effective_preference_state: evaluation.effective_preference_state,
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      class Store
+        def self.find(recipient_id:, notification_type_key:)
+          new.find(recipient_id:, notification_type_key:)
+        end
+
+        def self.upsert!(recipient_id:, notification_type_key:, preference_state:)
+          new.upsert!(recipient_id:, notification_type_key:, preference_state:)
+        end
+
+        def self.delete!(recipient_id:, notification_type_key:)
+          new.delete!(recipient_id:, notification_type_key:)
+        end
+
+        def find(recipient_id:, notification_type_key:)
+          record = Messaging::NotificationPreference.find_for(
+            recipient_id:,
+            notification_type_key:,
+          )
+          return nil if record.nil?
+
+          PreferenceState.normalize(record.state)
+        rescue ActiveRecord::ActiveRecordError => error
+          raise StoreError, "failed to load notification preference: #{error.message}"
+        rescue InvalidPreferenceStateError
+          raise
+        end
+
+        def upsert!(recipient_id:, notification_type_key:, preference_state:)
+          key = notification_type_key.to_s
+          declaration = lookup_declaration!(key)
+          validate_writable!(declaration)
+
+          normalized = PreferenceState.normalize(preference_state)
+          if normalized.nil?
+            raise InvalidPreferenceWriteError, "preference_state must be present"
+          end
+
+          validate_channels!(declaration, normalized)
+          validate_inbox!(declaration, normalized)
+
+          persist!(recipient_id:, notification_type_key: key, state: normalized.to_raw_hash)
+          normalized
+        rescue ActiveRecord::ActiveRecordError => error
+          raise StoreError, "failed to persist notification preference: #{error.message}"
+        end
+
+        def delete!(recipient_id:, notification_type_key:)
+          key = notification_type_key.to_s
+          record = Messaging::NotificationPreference.find_for(
+            recipient_id:,
+            notification_type_key: key,
+          )
+          return if record.nil?
+
+          record.destroy!
+          nil
+        rescue ActiveRecord::ActiveRecordError => error
+          raise StoreError, "failed to delete notification preference: #{error.message}"
+        end
+
+        private
+
+        def lookup_declaration!(key)
+          NotificationTypes.lookup(key)
+        rescue NotificationTypes::NotFoundError
+          raise UnknownTypeError, "notification type not registered: #{key}"
+        end
+
+        def validate_writable!(declaration)
+          return if declaration.user_configurable
+
+          raise InvalidPreferenceWriteError,
+                "notification type is not user-configurable: #{declaration.key}"
+        end
+
+        def validate_channels!(declaration, normalized)
+          extras = normalized.channels.keys - declaration.allowed_channels
+          return if extras.empty?
+
+          raise InvalidPreferenceWriteError,
+                "preference channels outside allowed set: #{extras.join(', ')}"
+        end
+
+        def validate_inbox!(declaration, normalized)
+          return if normalized.inbox.nil?
+          return if declaration.inbox_available
+
+          raise InvalidPreferenceWriteError,
+                "inbox preference is not available for notification type: #{declaration.key}"
+        end
+
+        def persist!(recipient_id:, notification_type_key:, state:)
+          record = Messaging::NotificationPreference.find_for(
+            recipient_id:,
+            notification_type_key:,
+          )
+
+          if record.nil?
+            begin
+              Messaging::NotificationPreference.create!(
+                user_id: recipient_id,
+                notification_type_key:,
+                state:,
+              )
+            rescue ActiveRecord::RecordNotUnique
+              record = Messaging::NotificationPreference.find_for(
+                recipient_id:,
+                notification_type_key:,
+              )
+              raise StoreError, "failed to persist notification preference" if record.nil?
+
+              record.update!(state:)
+            end
+          else
+            record.update!(state:)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      class StoreError < Error
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      SuppressedDestination = Data.define(:destination, :reason_class) do
+        def self.build(destination:, reason_class:)
+          unless ReasonClasses::ALL.include?(reason_class)
+            raise ArgumentError, "unknown reason_class: #{reason_class}"
+          end
+
+          dest =
+            if destination == :inbox || destination == "inbox"
+              :inbox
+            else
+              destination.to_s
+            end
+
+          new(destination: dest, reason_class:).freeze
+        end
+      end
+    end
+  end
+end

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

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