command_tower 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8bf05b7d610367efda3b4dce6349bfbd002891563a5f16a5688bbd2660717896
-  data.tar.gz: 5a31b97e28d791fbda2ad4899c121fe54c2f96e944c387c716d5541d7449c8f6
+  metadata.gz: b21d84c5b214027953938804efd0dba2a7523229c33f073bb010c5db82128755
+  data.tar.gz: 9c74f1edd4ff8774167b3b40e2423fdd8c286107ac58940f88fcae3f9808b04e
 SHA512:
-  metadata.gz: 6c1a8b5cf203cb35b4697f593324b94eb1a0e0a7c4d4b171c752b669a700862679a28cbbe494b54a632294181fa6ddf7d78aa117cf5a71e1deb7e9fc036b122e
-  data.tar.gz: 5232cb631564969ef269b82fd1b9c38ef820ee76523640a09b2846b380348b64e5c4dc62288b0a391edde0586b4e3d28559d26614788d26e7ba26ab8a96c7bd0
+  metadata.gz: 948f30f811a880da5001b091360eefaed16cb6f1ad52bd93bd57d753ce6cef8bfb6f1d425cac0e299da772bdbd931e115b1c30e80a90376587d084f50630ead2
+  data.tar.gz: b578871e337d1291d18819c7a37e455b6646fdba6f2f33ffa67fb94fd415aee5a5a7d1b5c9e3c628772724552b764b9c9c6732b076e2e89bc2be4d741376996a

data/app/serializers/command_tower/serializers/messaging/preferences/notification_serializer.rb

@@ -6,7 +6,7 @@ module CommandTower
       module Preferences
         class NotificationSerializer
           def self.serialize(notification)
-            {
+            payload = {
               key: notification.key,
               label: notification.label,
               description: notification.description,
@@ -16,6 +16,9 @@ module CommandTower
               inboxAvailable: notification.inbox_available,
               allowedChannels: notification.allowed_channels,
               availableChannels: notification.available_channels,
+              channelCatalog: serialize_channel_catalog(notification.channel_catalog),
+              destinations: serialize_destinations(notification.destinations),
+              settings: serialize_settings(notification.settings),
               urgency: notification.urgency,
               sound: notification.sound,
               preferences: {
@@ -24,7 +27,112 @@ module CommandTower
                 storedOverridePresent: notification.stored_override_present,
               },
             }
+
+            corrections = serialize_corrections(notification.corrections)
+            payload[:corrections] = corrections unless corrections.nil?
+
+            payload
+          end
+
+          def self.serialize_channel_catalog(entries)
+            Array(entries).map do |entry|
+              {
+                key: entry[:key],
+                label: entry[:label],
+                description: entry[:description],
+                order: entry[:order],
+                glyphKey: entry[:glyph_key],
+              }
+            end
+          end
+          private_class_method :serialize_channel_catalog
+
+          def self.serialize_settings(settings)
+            Array(settings).map do |entry|
+              hash = entry.respond_to?(:to_h) ? entry.to_h : entry
+              {
+                key: entry_value(hash, :key),
+                channelKey: entry_value(hash, :channel_key) || entry_value(hash, :channelKey),
+                control: entry_value(hash, :control),
+                label: entry_value(hash, :label),
+                description: entry_value(hash, :description),
+                editable: entry_value(hash, :editable),
+                effective: entry_value(hash, :effective),
+                options: serialize_setting_options(entry_value(hash, :options)),
+              }
+            end
+          end
+          private_class_method :serialize_settings
+
+          def self.serialize_setting_options(options)
+            return nil if options.nil?
+
+            Array(options).map do |option|
+              option_hash = option.respond_to?(:to_h) ? option.to_h : option
+              {
+                value: entry_value(option_hash, :value),
+                label: entry_value(option_hash, :label),
+                description: entry_value(option_hash, :description),
+              }
+            end
+          end
+          private_class_method :serialize_setting_options
+
+          def self.serialize_destinations(destinations)
+            destinations.to_h.transform_values do |entry|
+              serialize_destination_entry(entry)
+            end
+          end
+          private_class_method :serialize_destinations
+
+          def self.serialize_destination_entry(entry)
+            hash =
+              if entry.respond_to?(:to_h)
+                entry.to_h
+              else
+                entry
+              end
+
+            {
+              state: entry_value(hash, :state),
+              effective: entry_value(hash, :effective),
+              reasonCode: entry_value(hash, :reason_code) || entry_value(hash, :reasonCode),
+              reason: entry_value(hash, :reason),
+            }
+          end
+
+          def self.entry_value(hash, key)
+            return hash[key] if hash.key?(key)
+
+            string_key = key.to_s
+            return hash[string_key] if hash.key?(string_key)
+
+            nil
+          end
+          private_class_method :entry_value
+          private_class_method :serialize_destination_entry
+
+          def self.serialize_corrections(corrections)
+            return nil if corrections.nil?
+
+            Array(corrections).map do |entry|
+              hash =
+                if entry.respond_to?(:to_h)
+                  entry.to_h
+                else
+                  entry
+                end
+
+              {
+                channelKey: hash[:channel_key] || hash["channelKey"],
+                submitted: hash[:submitted],
+                effective: hash[:effective],
+                reasonCode: hash[:reason_code] || hash["reasonCode"],
+                reason: hash[:reason],
+              }
+            end
           end
+          private_class_method :serialize_corrections
         end
       end
     end

data/app/services/command_tower/messaging/channels/definition.rb

@@ -6,6 +6,9 @@ module CommandTower
       Definition = Data.define(
         :key,
         :label,
+        :description,
+        :order,
+        :glyph_key,
         :kind,
         :supports_endpoint_records,
         :identity_backed,

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

@@ -12,6 +12,9 @@ module CommandTower
         Definition.new(
           key: "inbox",
           label: "Inbox",
+          description: "In-app messages",
+          order: 0,
+          glyph_key: "inbox",
           kind: :inbox,
           supports_endpoint_records: false,
           identity_backed: false,
@@ -20,6 +23,9 @@ module CommandTower
         Definition.new(
           key: "email",
           label: "Email",
+          description: "Email to your account address",
+          order: 1,
+          glyph_key: "mail",
           kind: :external,
           supports_endpoint_records: false,
           identity_backed: true,
@@ -28,6 +34,9 @@ module CommandTower
         Definition.new(
           key: "sms",
           label: "SMS",
+          description: "Text messages",
+          order: 2,
+          glyph_key: "message",
           kind: :external,
           supports_endpoint_records: false,
           identity_backed: true,
@@ -36,6 +45,9 @@ module CommandTower
         Definition.new(
           key: "push",
           label: "Push",
+          description: "Alerts on this device",
+          order: 3,
+          glyph_key: "bell",
           kind: :external,
           supports_endpoint_records: true,
           identity_backed: false,
@@ -44,6 +56,9 @@ module CommandTower
         Definition.new(
           key: "pushover",
           label: "Pushover",
+          description: "Pushover alerts",
+          order: 4,
+          glyph_key: "radio",
           kind: :external,
           supports_endpoint_records: true,
           identity_backed: false,

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

@@ -27,6 +27,7 @@ module CommandTower
         :urgency,
         :sound,
         :deep_link_required,
+        :destination_locks,
       ) do
         def self.build(
           key:,
@@ -51,7 +52,8 @@ module CommandTower
           badge_eligible: false,
           urgency: nil,
           sound: nil,
-          deep_link_required: false
+          deep_link_required: false,
+          destination_locks: {}
         )
           new(
             key: key.nil? ? nil : key.to_s,
@@ -93,9 +95,21 @@ module CommandTower
             # NPB-5. Push-capable types that are not inbox-backed must set this
             # so Produce can reject a missing metadata deep_link.
             deep_link_required: !!deep_link_required,
+            destination_locks: freeze_destination_locks(destination_locks),
           ).freeze
         end
 
+        def self.freeze_destination_locks(locks)
+          return {}.freeze if locks.nil? || locks.empty?
+
+          unless locks.respond_to?(:to_h)
+            return {}.freeze
+          end
+
+          locks.to_h.transform_keys(&:to_s).transform_values(&:to_s).freeze
+        end
+        private_class_method :freeze_destination_locks
+
         def self.freeze_channel_list(channels)
           return nil if channels.nil?
 

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

@@ -87,6 +87,8 @@ module CommandTower
             errors << "push-capable types must be inbox-backed or declare deep_link_required"
           end
 
+          validate_destination_locks(errors, declaration)
+
           errors
         end
 
@@ -193,6 +195,57 @@ module CommandTower
         end
         private_class_method :push_capable?
 
+        def self.validate_destination_locks(errors, declaration)
+          locks = declaration.destination_locks
+          return if locks.nil? || locks.empty?
+
+          unless locks.is_a?(Hash)
+            errors << "destination_locks must be a hash"
+            return
+          end
+
+          defaults =
+            ::CommandTower::Messaging::Preferences::PreferenceState.from_declaration_default(
+              declaration.default_preference_state,
+            )
+          required_channels =
+            if declaration.mandatory
+              declaration.default_channels & declaration.allowed_channels
+            else
+              []
+            end
+          required_inbox =
+            declaration.mandatory && declaration.inbox_available && defaults.inbox != false
+
+          locks.each do |raw_key, raw_value|
+            key = raw_key.to_s
+            value = raw_value.to_s
+
+            unless %w[forced_on forced_off].include?(value)
+              errors << "destination_locks[#{key.inspect}] must be forced_on or forced_off"
+            end
+
+            permitted =
+              if key == "inbox"
+                declaration.inbox_available
+              else
+                declaration.allowed_channels.include?(key)
+              end
+            unless permitted
+              errors << "destination_locks contains unknown destination: #{key.inspect}"
+            end
+
+            next unless value == "forced_off" && declaration.mandatory
+
+            if key == "inbox" && required_inbox
+              errors << "destination_locks cannot force_off mandatory inbox"
+            elsif required_channels.include?(key)
+              errors << "destination_locks cannot force_off mandatory channel: #{key}"
+            end
+          end
+        end
+        private_class_method :validate_destination_locks
+
         def self.validate_channel_list(errors, channels, field:)
           channels.each do |channel|
             key = channel.to_s

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

@@ -58,43 +58,14 @@ module CommandTower
         end
 
         def build_notification(declaration, evaluation, recipient_ready_keys)
-          effective_state = evaluation.effective_preference_state || {}
-          effective_channels = effective_state["channels"] || {}
-          channels =
-            declaration.allowed_channels.to_h do |channel|
-              [channel, !!effective_channels[channel]]
-            end
-
-          inbox_enabled =
-            if effective_state.key?("inbox")
-              !!effective_state["inbox"]
-            else
-              evaluation.inbox_permitted
-            end
-
           available =
             declaration.allowed_channels & @platform_enabled_channels & recipient_ready_keys
 
-          blocks = EffectiveChoice.call(
+          NotificationAssembly.build(
             declaration:,
-            stored: Store.find(recipient_id: @recipient_id, notification_type_key: declaration.key),
-          )
-
-          ::CommandTower::Messaging::Preferences::CatalogNotificationResult.build(
-            key: declaration.key,
-            label: declaration.label,
-            description: declaration.description,
-            order: declaration.type_order,
-            configurable: declaration.user_configurable,
-            mandatory: declaration.mandatory,
-            inbox_available: declaration.inbox_available,
-            allowed_channels: declaration.allowed_channels,
+            evaluation:,
             available_channels: available,
-            inbox_enabled:,
-            channels:,
-            stored_override_present: evaluation.stored_override_present,
-            urgency: blocks[:urgency],
-            sound: blocks[:sound],
+            recipient_id: @recipient_id,
           )
         end
       end

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

@@ -18,6 +18,10 @@ module CommandTower
         :stored_override_present,
         :urgency,
         :sound,
+        :channel_catalog,
+        :destinations,
+        :corrections,
+        :settings,
       ) do
         def self.build(
           key:,
@@ -33,7 +37,11 @@ module CommandTower
           channels:,
           stored_override_present:,
           urgency:,
-          sound:
+          sound:,
+          channel_catalog: [],
+          destinations: {},
+          corrections: nil,
+          settings: []
         )
           frozen_channels =
             channels.to_h.transform_keys(&:to_s).transform_values { |value| !!value }.freeze
@@ -53,9 +61,35 @@ module CommandTower
             stored_override_present: !!stored_override_present,
             urgency: freeze_block(urgency),
             sound: freeze_block(sound),
+            channel_catalog: freeze_channel_catalog(channel_catalog),
+            destinations: freeze_destinations(destinations),
+            corrections: freeze_corrections(corrections),
+            settings: freeze_settings(settings),
           ).freeze
         end
 
+        def self.freeze_settings(settings)
+          Array(settings).map(&:freeze).freeze
+        end
+        private_class_method :freeze_settings
+
+        def self.freeze_channel_catalog(entries)
+          Array(entries).map(&:freeze).freeze
+        end
+        private_class_method :freeze_channel_catalog
+
+        def self.freeze_destinations(destinations)
+          destinations.to_h.transform_keys(&:to_s).transform_values(&:freeze).freeze
+        end
+        private_class_method :freeze_destinations
+
+        def self.freeze_corrections(corrections)
+          return nil if corrections.nil?
+
+          Array(corrections).map(&:freeze).freeze
+        end
+        private_class_method :freeze_corrections
+
         def self.freeze_block(block)
           hash = block.to_h
           allowed = hash[:allowed]

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      class ChannelCatalog
+        def self.entries_for(declaration)
+          ::CommandTower::Messaging::Channels::DEFINITIONS.filter_map do |definition|
+            next if definition.inbox? && !declaration.inbox_available
+            next if definition.external? && !declaration.allowed_channels.include?(definition.key)
+
+            {
+              key: definition.key,
+              label: definition.label,
+              description: definition.description,
+              order: definition.order,
+              glyph_key: definition.glyph_key,
+            }.freeze
+          end.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      class Corrections
+        CorrectionEntry = Data.define(
+          :channel_key,
+          :submitted,
+          :effective,
+          :reason_code,
+          :reason,
+        )
+
+        def self.build(submitted:, destinations:)
+          return [].freeze if submitted.nil? || submitted.empty?
+
+          submitted.filter_map do |channel_key, submitted_value|
+            destination = destinations[channel_key.to_s]
+            next if destination.nil?
+
+            entry = normalize_destination(destination)
+
+            next if submitted_value == entry.effective
+
+            CorrectionEntry.new(
+              channel_key: channel_key.to_s,
+              submitted: !!submitted_value,
+              effective: entry.effective,
+              reason_code: entry.reason_code,
+              reason: entry.reason,
+            )
+          end.freeze
+        end
+
+        def self.normalize_destination(destination)
+          return destination if destination.is_a?(Destinations::DestinationEntry)
+
+          Destinations::DestinationEntry.new(
+            state: destination.fetch(:state) { destination["state"] },
+            effective: destination.fetch(:effective) { destination["effective"] },
+            reason_code: destination.fetch(:reason_code) { destination["reasonCode"] },
+            reason: destination.fetch(:reason) { destination["reason"] },
+          )
+        end
+        private_class_method :normalize_destination
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      class DestinationLocks
+        def self.apply(declaration:, state:)
+          locks = declaration.destination_locks
+          return state if locks.nil? || locks.empty?
+
+          channels = state.channels.to_h.dup
+          inbox = state.inbox
+
+          locks.each do |key, lock|
+            enabled = lock.to_s == "forced_on"
+            if key.to_s == "inbox"
+              inbox = enabled
+            else
+              channels[key.to_s] = enabled
+            end
+          end
+
+          PreferenceState.new(
+            channels: channels.freeze,
+            inbox:,
+            urgency: state.urgency,
+            sound: state.sound,
+          ).freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      class Destinations
+        REASONS = {
+          "required" => "This notification is required on this destination.",
+          "locked_on" => "This destination is locked on.",
+          "locked_off" => "This destination is locked off.",
+          "unavailable" => "This destination is unavailable.",
+        }.freeze
+
+        DestinationEntry = Data.define(:state, :effective, :reason_code, :reason)
+
+        def self.call(declaration:, evaluation:, available_channels:)
+          new(declaration:, evaluation:, available_channels:).call
+        end
+
+        def initialize(declaration:, evaluation:, available_channels:)
+          @declaration = declaration
+          @evaluation = evaluation
+          @available_channels = Array(available_channels).map(&:to_s).freeze
+          @locks = declaration.destination_locks || {}.freeze
+          @defaults = PreferenceState.from_declaration_default(declaration.default_preference_state)
+        end
+
+        def call
+          ChannelCatalog.entries_for(@declaration).to_h do |entry|
+            key = entry[:key]
+            [key, resolve(key).to_h.freeze]
+          end.freeze
+        end
+
+        private
+
+        def resolve(key)
+          if key == "inbox"
+            resolve_inbox
+          else
+            resolve_channel(key)
+          end
+        end
+
+        def resolve_channel(channel)
+          if unavailable_external?(channel)
+            return build_entry(state: "unavailable", effective: false, reason_code: "unavailable")
+          end
+
+          lock = @locks[channel]
+          return build_entry(state: "forced_off", effective: false, reason_code: "locked_off") if lock == "forced_off"
+          return build_entry(state: "forced_on", effective: true, reason_code: "locked_on") if lock == "forced_on"
+
+          member_on = member_channel_enabled?(channel)
+          if mandatory_required_channel?(channel) && !member_on
+            return build_entry(state: "forced_on", effective: true, reason_code: "required")
+          end
+
+          build_entry(state: "editable", effective: member_on, reason_code: nil)
+        end
+
+        def resolve_inbox
+          lock = @locks["inbox"]
+          return build_entry(state: "forced_off", effective: false, reason_code: "locked_off") if lock == "forced_off"
+          return build_entry(state: "forced_on", effective: true, reason_code: "locked_on") if lock == "forced_on"
+
+          member_on = member_inbox_enabled?
+          if mandatory_required_inbox? && !member_on
+            return build_entry(state: "forced_on", effective: true, reason_code: "required")
+          end
+
+          build_entry(state: "editable", effective: member_on, reason_code: nil)
+        end
+
+        def unavailable_external?(channel)
+          @declaration.allowed_channels.include?(channel) && !@available_channels.include?(channel)
+        end
+
+        def mandatory_required_channel?(channel)
+          @declaration.mandatory &&
+            (@declaration.default_channels & @declaration.allowed_channels).include?(channel)
+        end
+
+        def mandatory_required_inbox?
+          @declaration.mandatory && @declaration.inbox_available && @defaults.inbox != false
+        end
+
+        def member_channel_enabled?(channel)
+          state = @evaluation.effective_preference_state || {}
+          channels = state["channels"] || {}
+          if channels.key?(channel)
+            !!channels[channel]
+          else
+            @defaults.channel_enabled?(channel, default: true)
+          end
+        end
+
+        def member_inbox_enabled?
+          state = @evaluation.effective_preference_state || {}
+          if state.key?("inbox")
+            !!state["inbox"]
+          elsif @defaults.inbox.nil?
+            true
+          else
+            @defaults.inbox
+          end
+        end
+
+        def build_entry(state:, effective:, reason_code:)
+          reason = reason_code.nil? ? nil : REASONS.fetch(reason_code)
+          DestinationEntry.new(
+            state:,
+            effective: !!effective,
+            reason_code:,
+            reason:,
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      class NotificationAssembly
+        def self.build(
+          declaration:,
+          evaluation:,
+          available_channels:,
+          recipient_id:,
+          submitted_destinations: nil
+        )
+          effective_state = evaluation.effective_preference_state || {}
+          effective_channels = effective_state["channels"] || {}
+          channels =
+            declaration.allowed_channels.to_h do |channel|
+              [channel, !!effective_channels[channel]]
+            end
+
+          inbox_enabled =
+            if effective_state.key?("inbox")
+              !!effective_state["inbox"]
+            else
+              evaluation.inbox_permitted
+            end
+
+          channel_catalog = ChannelCatalog.entries_for(declaration)
+          destinations = Destinations.call(
+            declaration:,
+            evaluation:,
+            available_channels:,
+          )
+          corrections =
+            if submitted_destinations.nil?
+              nil
+            else
+              built = Corrections.build(submitted: submitted_destinations, destinations:)
+              built.empty? ? nil : built
+            end
+
+          blocks = EffectiveChoice.call(
+            declaration:,
+            stored: Store.find(recipient_id:, notification_type_key: declaration.key),
+          )
+
+          settings = SettingsProjection.for_notification(
+            declaration:,
+            blocks:,
+            destinations:,
+          )
+
+          CatalogNotificationResult.build(
+            key: declaration.key,
+            label: declaration.label,
+            description: declaration.description,
+            order: declaration.type_order,
+            configurable: declaration.user_configurable,
+            mandatory: declaration.mandatory,
+            inbox_available: declaration.inbox_available,
+            allowed_channels: declaration.allowed_channels,
+            available_channels:,
+            inbox_enabled:,
+            channels:,
+            stored_override_present: evaluation.stored_override_present,
+            urgency: blocks[:urgency],
+            sound: blocks[:sound],
+            channel_catalog:,
+            destinations:,
+            corrections:,
+            settings:,
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      module SettingControls
+        IMPLEMENTED = %w[single_select].freeze
+        RESERVED = %w[boolean multi_select read_only].freeze
+
+        class UnsupportedControlError < StandardError; end
+
+        def self.validate_implemented!(control)
+          normalized = control.to_s
+          if RESERVED.include?(normalized) && !IMPLEMENTED.include?(normalized)
+            raise UnsupportedControlError,
+                  "setting control #{normalized.inspect} is reserved and not implemented"
+          end
+          return if IMPLEMENTED.include?(normalized)
+
+          raise UnsupportedControlError, "unknown setting control: #{normalized.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Preferences
+      class SettingsProjection
+        PUSH_CHANNEL = "push"
+
+        URGENCY_LABELS = {
+          "normal" => "Normal",
+          "time_sensitive" => "Time Sensitive",
+          "critical" => "Critical",
+        }.freeze
+
+        URGENCY_DESCRIPTIONS = {
+          "normal" => "Delivered with the device’s normal notification behavior.",
+          "time_sensitive" => "Asks the device to treat this alert as time sensitive.",
+          "critical" =>
+            "Highest declared urgency. Actual delivery behavior depends on the application and device capabilities.",
+        }.freeze
+
+        SettingEntry = Data.define(
+          :key,
+          :channel_key,
+          :control,
+          :label,
+          :description,
+          :editable,
+          :effective,
+          :options,
+        )
+
+        SingleSelectDefinition = Data.define(
+          :key,
+          :channel_key,
+          :label,
+          :description,
+          :effective,
+          :options,
+        )
+
+        def self.for_notification(declaration:, blocks:, destinations:)
+          return [].freeze unless push_destination?(declaration, destinations)
+
+          definitions = []
+          urgency = blocks[:urgency]
+          if urgency[:selectable]
+            definitions << urgency_definition(urgency)
+          end
+
+          sound = blocks[:sound]
+          if sound[:selectable]
+            definitions << sound_definition(sound)
+          end
+
+          build(definitions)
+        end
+
+        def self.build(definitions)
+          Array(definitions).filter_map do |definition|
+            project_single_select(definition)
+          end.freeze
+        end
+
+        def self.push_destination?(declaration, destinations)
+          declaration.allowed_channels.include?(PUSH_CHANNEL) &&
+            destinations.key?(PUSH_CHANNEL)
+        end
+
+        def self.urgency_definition(urgency_block)
+          options =
+            Array(urgency_block[:allowed]).map do |value|
+              {
+                value:,
+                label: URGENCY_LABELS.fetch(value),
+                description: URGENCY_DESCRIPTIONS.fetch(value),
+              }.freeze
+            end
+
+          SingleSelectDefinition.new(
+            key: "urgency",
+            channel_key: PUSH_CHANNEL,
+            label: "Urgency",
+            description: nil,
+            effective: urgency_block[:effective].to_s,
+            options: options.freeze,
+          )
+        end
+
+        def self.sound_definition(sound_block)
+          options =
+            Array(sound_block[:allowed]).map do |entry|
+              id = entry[:id] || entry["id"]
+              label = entry[:label] || entry["label"]
+              { value: id, label:, description: nil }.freeze
+            end
+
+          SingleSelectDefinition.new(
+            key: "sound",
+            channel_key: PUSH_CHANNEL,
+            label: "Sound",
+            description: nil,
+            effective: sound_block[:effective].to_s,
+            options: options.freeze,
+          )
+        end
+
+        def self.project_single_select(definition)
+          SettingControls.validate_implemented!("single_select")
+
+          SettingEntry.new(
+            key: definition.key,
+            channel_key: definition.channel_key,
+            control: "single_select",
+            label: definition.label,
+            description: definition.description,
+            editable: true,
+            effective: definition.effective,
+            options: definition.options,
+          ).to_h.freeze
+        end
+        private_class_method :project_single_select
+      end
+    end
+  end
+end

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

@@ -25,10 +25,14 @@ module CommandTower
           validate_settings_visible!(declaration)
           validate_writable!(declaration)
 
+          submitted_destinations = nil
+
           if reset_request?
             persist_reset!
           else
-            candidate = build_candidate_state!(declaration)
+            patch_hash = normalized_preference_hash
+            submitted_destinations = extract_submitted_destinations(patch_hash)
+            candidate = build_candidate_state!(declaration, patch_hash:)
             sparse = sparsify(declaration, candidate)
             persist_sparse!(sparse)
           end
@@ -39,7 +43,12 @@ module CommandTower
             platform_enabled_channels: @platform_enabled_channels,
           )
 
-          build_notification_result(declaration, evaluation, recipient_ready_channel_keys)
+          build_notification_result(
+            declaration,
+            evaluation,
+            recipient_ready_channel_keys,
+            submitted_destinations:,
+          )
         end
 
         private
@@ -79,24 +88,60 @@ module CommandTower
           @preference_state.respond_to?(:to_h) && @preference_state.to_h.empty?
         end
 
-        def build_candidate_state!(declaration)
+        def normalized_preference_hash
           unless @preference_state.respond_to?(:to_h)
             raise InvalidPreferenceStateError, "preference_state must be a hash-like object"
           end
 
-          hash = @preference_state.to_h.transform_keys(&:to_s)
+          @preference_state.to_h.transform_keys(&:to_s)
+        end
+
+        def extract_submitted_destinations(hash)
+          submitted = {}
+          submitted["inbox"] = hash["inbox"] if hash.key?("inbox")
+          if hash.key?("channels") && hash["channels"].respond_to?(:to_h)
+            hash["channels"].to_h.each do |raw_key, raw_value|
+              submitted[raw_key.to_s] = raw_value
+            end
+          end
+          submitted.freeze
+        end
+
+        def build_candidate_state!(declaration, patch_hash: nil)
+          hash = patch_hash || normalized_preference_hash
           unknown_keys = hash.keys - %w[channels inbox urgency sound]
           if unknown_keys.any?
             raise InvalidPreferenceWriteError,
                   "unsupported preference keys: #{unknown_keys.join(', ')}"
           end
 
-          channels = parse_channels!(declaration, hash["channels"])
-          inbox = parse_inbox!(declaration, hash)
+          patch = build_patch_partial!(declaration, hash)
+          merged = patch.merge_over(stored_member_state)
+          DestinationLocks.apply(declaration:, state: merged)
+        end
+
+        def stored_member_state
+          Store.find(
+            recipient_id: @recipient_id,
+            notification_type_key: @notification_type_key,
+          ) || empty_stored_member_state
+        end
+
+        def empty_stored_member_state
+          PreferenceState.new(channels: {}.freeze, inbox: nil, urgency: nil, sound: nil).freeze
+        end
+
+        def build_patch_partial!(declaration, hash)
+          channels =
+            if hash.key?("channels")
+              parse_channels!(declaration, hash["channels"])
+            else
+              {}.freeze
+            end
 
           PreferenceState.new(
             channels: channels.freeze,
-            inbox:,
+            inbox: parse_inbox!(declaration, hash),
             urgency: parse_choice!(declaration, hash, "urgency"),
             sound: parse_choice!(declaration, hash, "sound"),
           ).freeze
@@ -234,44 +279,16 @@ module CommandTower
           current.to_raw_hash == sparse.to_raw_hash
         end
 
-        def build_notification_result(declaration, evaluation, recipient_ready_keys)
-          effective_state = evaluation.effective_preference_state || {}
-          effective_channels = effective_state["channels"] || {}
-          channels =
-            declaration.allowed_channels.to_h do |channel|
-              [channel, !!effective_channels[channel]]
-            end
-
-          inbox_enabled =
-            if effective_state.key?("inbox")
-              !!effective_state["inbox"]
-            else
-              evaluation.inbox_permitted
-            end
-
+        def build_notification_result(declaration, evaluation, recipient_ready_keys, submitted_destinations: nil)
           available =
             declaration.allowed_channels & @platform_enabled_channels & recipient_ready_keys
 
-          blocks = EffectiveChoice.call(
+          NotificationAssembly.build(
             declaration:,
-            stored: Store.find(recipient_id: @recipient_id, notification_type_key: @notification_type_key),
-          )
-
-          ::CommandTower::Messaging::Preferences::CatalogNotificationResult.build(
-            key: declaration.key,
-            label: declaration.label,
-            description: declaration.description,
-            order: declaration.type_order,
-            configurable: declaration.user_configurable,
-            mandatory: declaration.mandatory,
-            inbox_available: declaration.inbox_available,
-            allowed_channels: declaration.allowed_channels,
+            evaluation:,
             available_channels: available,
-            inbox_enabled:,
-            channels:,
-            stored_override_present: evaluation.stored_override_present,
-            urgency: blocks[:urgency],
-            sound: blocks[:sound],
+            recipient_id: @recipient_id,
+            submitted_destinations:,
           )
         end
       end

data/docs/upgrades/0.21.0.md

@@ -0,0 +1,31 @@
+# Upgrade: CommandTower 0.21.0
+
+**From:** `0.20.0`  
+**To:** `0.21.0`
+
+Minor release: member notification preferences expose a channel catalog, per-destination state, and ordered push settings, and preference PATCH merges onto stored member state. Legacy `urgency` and `sound` blocks remain. Push delivery and Inbox behavior are unchanged.
+
+## Host-visible changes
+
+| Change | Host impact |
+|--------|-------------|
+| Preference GET / PATCH payload | Each settings-visible notification includes `channelCatalog` (`key`, `label`, `description`, `order`, `glyphKey`), `destinations` (`state`, `effective`, `reasonCode`, `reason`), and `settings` (`single_select` rows). `urgency` and `sound` blocks stay. |
+| Channel catalog | Platform channels carry presentation copy: Inbox, Email, SMS, Push, Pushover (`description`, `order`, `glyphKey`). |
+| `settings` | When Push is a destination, urgency and sound project as ordered `single_select` rows. Option labels and descriptions are server-owned. Sound options use catalog labels. |
+| Preference PATCH | Partial bodies merge onto stored member state. Omitted `channels`, `inbox`, `urgency`, and `sound` are preserved. Validation still runs before any write. |
+| `destination_locks` | Optional notification declaration (`forced_on` / `forced_off` per destination). Applied after the merge. Defaults to `{}`. Cannot force off a mandatory destination. |
+| `corrections` | Present only when the member explicitly submitted a destination boolean that the server corrected (locks or mandatory required). Omitted keys do not emit corrections. |
+
+## Host actions
+
+1. Bump gem to `0.21.0` (or `>= 0.21.0`).
+2. **No new migration.** Run `bundle exec rails db:migrate` only if other pending host migrations exist.
+3. Clients that render notification settings should read `channelCatalog`, `destinations`, and `settings`. Existing `urgency` / `sound` consumers keep working.
+4. Set `destination_locks` on a notification declaration only when a destination must stay forced on or off.
+
+## Not in this release
+
+- No new HTTP routes.
+- No Inbox document or rendering changes.
+- No push execution, Expo, or email retry changes.
+- No change to preference PATCH keys (`channels`, `inbox`, `urgency`, `sound`).

data/docs/upgrades/README.md

@@ -4,6 +4,7 @@ Host-facing upgrade / change summaries for CommandTower releases.
 
 | Version | Summary |
 |---------|---------|
+| [0.21.0](0.21.0.md) | Notification preference reads: channel catalog, destinations, settings rows; PATCH merges onto stored member state |
 | [0.20.0](0.20.0.md) | Push delivery certainty: JSON `provider_metadata` caster; duplicate-averse push recovery and Expo submission guards |
 | [0.19.0](0.19.0.md) | Push presentation: badge, urgency, sound, deep links; Expo ticket and receipt metadata; preference urgency and sound |
 | [0.18.0](0.18.0.md) | Inbox conversations: optional Produce identity, grouped list entries, `GET /me/inbox/conversation` window of at most 5, accept-time presentation snapshot |

data/lib/command_tower/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CommandTower
-  VERSION = "0.20.0"
+  VERSION = "0.21.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: command_tower
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.0
 platform: ruby
 authors:
 - matt-taylor
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-10-15 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phonelib
@@ -572,6 +572,10 @@ files:
 - app/services/command_tower/messaging/preferences/catalog_category_result.rb
 - app/services/command_tower/messaging/preferences/catalog_notification_result.rb
 - app/services/command_tower/messaging/preferences/catalog_result.rb
+- app/services/command_tower/messaging/preferences/channel_catalog.rb
+- app/services/command_tower/messaging/preferences/corrections.rb
+- app/services/command_tower/messaging/preferences/destination_locks.rb
+- app/services/command_tower/messaging/preferences/destinations.rb
 - app/services/command_tower/messaging/preferences/effective_choice.rb
 - app/services/command_tower/messaging/preferences/error.rb
 - app/services/command_tower/messaging/preferences/evaluation_result.rb
@@ -579,9 +583,12 @@ files:
 - app/services/command_tower/messaging/preferences/invalid_preference_state_error.rb
 - app/services/command_tower/messaging/preferences/invalid_preference_write_error.rb
 - app/services/command_tower/messaging/preferences/not_settings_visible_error.rb
+- app/services/command_tower/messaging/preferences/notification_assembly.rb
 - app/services/command_tower/messaging/preferences/preference_state.rb
 - app/services/command_tower/messaging/preferences/reason_classes.rb
 - app/services/command_tower/messaging/preferences/resolve.rb
+- app/services/command_tower/messaging/preferences/setting_controls.rb
+- app/services/command_tower/messaging/preferences/settings_projection.rb
 - app/services/command_tower/messaging/preferences/store.rb
 - app/services/command_tower/messaging/preferences/store_error.rb
 - app/services/command_tower/messaging/preferences/suppressed_destination.rb
@@ -861,6 +868,7 @@ files:
 - docs/upgrades/0.18.0.md
 - docs/upgrades/0.19.0.md
 - docs/upgrades/0.20.0.md
+- docs/upgrades/0.21.0.md
 - docs/upgrades/README.md
 - lib/command_tower.rb
 - lib/command_tower/admin_scope.rb