command_tower 0.18.0 → 0.19.0

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    # Registered push sounds. The engine owns System Default, a logical id that needs no
+    # bundled native asset. Hosts append custom entries through
+    # `config.messaging.sounds` (`{ id:, label:, asset: }`); `asset` is the native file
+    # reference. Whether the file is physically bundled is verified later (IOS), not here.
+    module SoundCatalog
+      module_function
+
+      ID_FORMAT = /\A[a-z][a-z0-9_]*\z/
+      # iOS plays a custom push sound only for a bundled file name with one of these extensions.
+      ASSET_EXTENSIONS = %w[.wav .aiff .caf].freeze
+      SYSTEM_DEFAULT = { id: "default", label: "System Default", asset: nil }.freeze
+
+      def entries
+        [SYSTEM_DEFAULT] + host_entries.grep(Hash).map { |entry| entry.transform_keys(&:to_sym).freeze }
+      end
+
+      def ids
+        entries.pluck(:id)
+      end
+
+      def fetch(id)
+        entries.find { |entry| entry[:id] == id.to_s }
+      end
+
+      # Messages for an invalid host catalog; empty when valid. Registry seal raises on them.
+      def validation_errors
+        errors = []
+        seen = [SYSTEM_DEFAULT[:id]]
+
+        host_entries.each_with_index do |entry, index|
+          label = "sounds[#{index}]"
+          unless entry.is_a?(Hash)
+            errors << "#{label} must be a hash"
+            next
+          end
+
+          entry = entry.transform_keys(&:to_sym)
+          errors.concat(entry_errors(entry, label:, seen:))
+          seen << entry[:id]
+        end
+
+        errors
+      end
+
+      def host_entries
+        Array(CommandTower.config.messaging.sounds)
+      end
+      private_class_method :host_entries
+
+      def entry_errors(entry, label:, seen:)
+        id = entry[:id]
+        errors = []
+
+        if !id.is_a?(String) || !id.match?(ID_FORMAT)
+          errors << "#{label} id must match #{ID_FORMAT.inspect}"
+        elsif seen.include?(id)
+          reason = id == SYSTEM_DEFAULT[:id] ? "reserved for System Default" : "duplicated"
+          errors << "#{label} id #{id.inspect} is #{reason}"
+        end
+
+        errors << "#{label} label must be present" unless present_string?(entry[:label])
+        errors.concat(asset_errors(entry[:asset], label:))
+        errors
+      end
+      private_class_method :entry_errors
+
+      def asset_errors(asset, label:)
+        return ["#{label} asset must be present"] unless present_string?(asset)
+        return [] if ASSET_EXTENSIONS.include?(File.extname(asset).downcase)
+
+        ["#{label} asset must end in #{ASSET_EXTENSIONS.join(', ')}"]
+      end
+      private_class_method :asset_errors
+
+      def present_string?(value)
+        value.is_a?(String) && !value.strip.empty?
+      end
+      private_class_method :present_string?
+    end
+  end
+end

data/app/services/command_tower/services/account/push/send_self_test.rb

@@ -31,13 +31,19 @@ module CommandTower
               return
             end
 
+            deep_link = CommandTower.config.messaging.expo.resolve_self_test_deep_link
+            if deep_link.nil?
+              context.fail!(application_error: CommandTower::Errors::Account::PushTestDestinationError.new)
+              return
+            end
+
             produce_result = CommandTower::Services::Messaging::Communications::Produce.call(
               user:,
               notification_type_key: NOTIFICATION_TYPE_KEY,
               host_event_identity: "push_delivery_test/#{user.id}/#{SecureRandom.uuid}",
               title: TITLE,
               body: BODY,
-              metadata: {},
+              metadata: { "deep_link" => deep_link },
               platform_enabled_channels: CommandTower::Services::Messaging::Preferences::PlatformEnabledChannels.call,
             )
             unless produce_result.success?

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

@@ -25,6 +25,15 @@ module CommandTower
               return
             end
 
+            if missing_required_deep_link?
+              context.fail!(
+                application_error: CommandTower::Errors::ValidationError.new(
+                  details: { messaging: "deep_link is required" },
+                ),
+              )
+              return
+            end
+
             accept_result = CommandTower::Messaging.accept(
               recipient_id: recipient_result.data[:recipient_id],
               notification_type_key:,
@@ -65,6 +74,24 @@ module CommandTower
           rescue CommandTower::Messaging::Accept::Error
             context.fail!(application_error: CommandTower::Errors::InternalError.new)
           end
+
+          private
+
+          def missing_required_deep_link?
+            return false unless CommandTower::Messaging::NotificationTypes.registered?(notification_type_key)
+
+            declaration = CommandTower::Messaging::NotificationTypes.lookup(notification_type_key)
+            return false unless declaration.deep_link_required
+
+            !metadata_deep_link_present?
+          end
+
+          def metadata_deep_link_present?
+            return false unless metadata.is_a?(Hash)
+
+            value = metadata["deep_link"] || metadata[:deep_link]
+            value.is_a?(String) && !value.strip.empty?
+          end
         end
       end
     end

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

@@ -116,7 +116,11 @@ module CommandTower
           validate :user, is_a: User, required: true
 
           def call
-            with_recipient { |recipient_id| context.count = CommandTower::Messaging::Inbox.unread_count(recipient_id:).count }
+            with_recipient do |recipient_id|
+              result = CommandTower::Messaging::Inbox.unread_count(recipient_id:)
+              context.count = result.count
+              context.badge_count = result.badge_count
+            end
           end
         end
 

data/app/workflows/command_tower/workflows/me/error_mapping.rb

@@ -26,6 +26,7 @@ module CommandTower
                CommandTower::Errors::Account::PushoverVerificationFailedError,
                CommandTower::Errors::Account::PushEndpointNotFoundError,
                CommandTower::Errors::Account::PushTestNoEndpointError,
+               CommandTower::Errors::Account::PushTestDestinationError,
                CommandTower::Errors::ValidationError
             :unprocessable_entity
           when CommandTower::Errors::Account::PhoneVerificationThrottledError,

data/app/workflows/command_tower/workflows/messaging/execution/deliver_workflow.rb

@@ -154,7 +154,7 @@ module CommandTower
 
           def load_delivery(channel_delivery_id)
             CommandTower::Messaging::ChannelDelivery.includes(
-              communication: %i[user destination_plan],
+              communication: %i[user destination_plan inbox_item],
             ).find_by(id: channel_delivery_id)
           end
 
@@ -172,6 +172,7 @@ module CommandTower
               communication:,
               channel_key: delivery.channel_key,
               recipient_address:,
+              channel_delivery: delivery,
             )
 
             CommandTower::Messaging::Execution::OperationLogger.render_succeeded(
@@ -204,18 +205,21 @@ module CommandTower
               CommandTower::Messaging::Execution::OperationLogger.adapter_accepted(
                 channel_delivery: delivery,
                 delivery_attempt: attempt,
+                provider_metadata: result.provider_metadata,
               )
             elsif result.retryable_failure?
               CommandTower::Messaging::Execution::OperationLogger.adapter_retryable(
                 channel_delivery: delivery,
                 delivery_attempt: attempt,
                 error_code: result.error_code,
+                provider_metadata: result.provider_metadata,
               )
             else
               CommandTower::Messaging::Execution::OperationLogger.adapter_terminal(
                 channel_delivery: delivery,
                 delivery_attempt: attempt,
                 error_code: result.error_code,
+                provider_metadata: result.provider_metadata,
               )
             end
           end

data/db/migrate/20261012000001_add_provider_metadata_to_messaging_delivery_attempts.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddProviderMetadataToMessagingDeliveryAttempts < ActiveRecord::Migration[7.2]
+  def change
+    add_column :messaging_delivery_attempts, :provider_metadata, :json
+  end
+end

data/db/migrate/20261012000002_add_finished_at_index_to_messaging_delivery_attempts.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class AddFinishedAtIndexToMessagingDeliveryAttempts < ActiveRecord::Migration[7.2]
+  def change
+    add_index :messaging_delivery_attempts, :finished_at,
+              name: "index_messaging_delivery_attempts_on_finished_at"
+  end
+end

data/docs/upgrades/0.19.0.md

@@ -0,0 +1,40 @@
+# Upgrade: CommandTower 0.19.0
+
+**From:** `0.18.0`  
+**To:** `0.19.0`
+
+Minor release: how a push presents itself, and Expo ticket and receipt facts. Notification types can declare badge eligibility, urgency, sound, and a required deep link. Preferences can store urgency and sound. Expo send records provider metadata, and the existing recovery job collects receipts afterward. Two new migrations.
+
+## Host-visible changes
+
+| Change | Host impact |
+|--------|-------------|
+| Notification type declaration | Optional `badge_eligible` (default false), `urgency`, `sound`, and `deep_link_required` (default false). Omitted urgency and sound stay fixed at `normal` and `default`. |
+| `config.messaging.sounds` | Host entries `{ id:, label:, asset: }` appended after System Default (`id: "default"`, no asset). Asset names end in `.wav`, `.aiff`, or `.caf`. Invalid catalogs fail registry seal. |
+| `config.messaging.expo.home_deep_link` | String or zero-argument Proc. Required when a push-capable type is registered and the Expo adapter is not `disabled`. Used when a push has no metadata `deep_link` and no live inbox item. |
+| `config.messaging.expo.self_test_deep_link` | String or zero-argument Proc. Resolved when `POST /me/push/test` runs. Blank fails the test before Produce. |
+| `config.messaging.expo.interruption_levels` | Subset of `normal`, `time_sensitive`, `critical`. Default is `["normal"]`. A declared urgency above this set degrades `critical` → `time_sensitive` → `normal`. |
+| Produce `metadata.deep_link` | Required when the type sets `deep_link_required` and the value is missing. Push-capable types that are not inbox-backed should set that flag. |
+| Preferences | `GET` catalog entries include `urgency` and `sound`. `PATCH` accepts `preferences.urgency` and `preferences.sound` alongside inbox and channels. |
+| Inbox unread | `Messaging::Inbox.unread_count` returns `count` and `badge_count`. `badge_count` is unread items whose type is badge-eligible. Expo `badge` is sent only for those types, including `0`. |
+| Push thread | A communication with `conversation_key` sends that key as the push thread id. |
+| Delivery attempts | Nullable `provider_metadata` JSON stores Expo ticket and receipt facts. `finished_at` is indexed for receipt collection. |
+| Recovery | After the existing redrive, receipt collection runs. A collection error is logged and does not fail the redrive. |
+
+## Host actions
+
+1. Bump gem to `0.19.0` (or `>= 0.19.0`).
+2. Install and migrate:
+   - `bundle exec rails command_tower:install:migrations`
+   - `bundle exec rails db:migrate`
+   - New files: `20261012000001_add_provider_metadata_to_messaging_delivery_attempts`, `20261012000002_add_finished_at_index_to_messaging_delivery_attempts`.
+3. If Expo is not `disabled` and any type allows push, set `config.messaging.expo.home_deep_link`. Registry seal raises without it.
+4. Set `self_test_deep_link` before members use push self-test.
+5. Add `time_sensitive` to `interruption_levels` only after the shipped iOS binary has the Time Sensitive capability. Leave `critical` off unless Apple granted Critical Alerts.
+6. Existing declarations that omit the new fields keep today's behavior: no badge, fixed normal urgency, System Default sound, deep link not required.
+
+## Not in this release
+
+- No host notification types. Hosts still register their own keys.
+- No bundled custom sound files. The catalog stores the asset name. The app binary supplies the file.
+- No backfill of `provider_metadata`. Existing attempts stay null.

data/docs/upgrades/README.md

@@ -4,6 +4,7 @@ Host-facing upgrade / change summaries for CommandTower releases.
 
 | Version | Summary |
 |---------|---------|
+| [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 |
 | [0.17.0](0.17.0.md) | Client-version-compatibility gating (`observe`/`enforce`); Rich Messaging Inbox `content` documents; host-overridable rendering templates; shared email theming |
 | [0.16.0](0.16.0.md) | Me experience-states (`GET`/`POST complete`); `host_key`; `user_experience_states` migration; `me_experience_states` RBAC |

data/lib/command_tower/configuration/messaging/config.rb

@@ -46,6 +46,16 @@ module CommandTower
           default: ->(_selection) { [] },
           default_shown: "->(_selection) { [] }"
 
+        add_composer :sounds,
+          desc: "Host-registered push sounds appended to the engine's System Default " \
+                "(id \"default\", no bundled asset). Array of { id:, label:, asset: } hashes; " \
+                "`asset` is the native file reference. Ids are lowercase snake_case and unique. " \
+                "Physical asset availability is verified by the iOS app, not here. " \
+                "Validated at notification-type registry seal.",
+          allowed: Array,
+          default: [],
+          default_shown: "[]"
+
         add_composer :sms,
           desc: "Messaging notification SMS delivery configuration (not Identity OTP)",
           allowed: Sms,

data/lib/command_tower/configuration/messaging/expo.rb

@@ -9,6 +9,9 @@ module CommandTower
         include ClassComposer::Generator
 
         ADAPTERS = %w[disabled fake log http].freeze
+        # Mirrors Messaging::NotificationTypes::URGENCY_LEVELS. Kept literal because this file
+        # loads before the app's autoloaded constants; a spec keeps the two in step.
+        INTERRUPTION_LEVELS = %w[normal time_sensitive critical].freeze
 
         add_composer :adapter,
           desc: "Expo Push delivery: disabled | fake | log | http. Default disabled (fail closed).",
@@ -45,6 +48,64 @@ module CommandTower
                 "(default 3600 = one hour).",
           allowed: Integer,
           default: 3600
+
+        add_composer :home_deep_link,
+          desc: "Host Home deep link used when a push has no metadata deep_link and no live inbox item. " \
+                "String or zero-argument Proc. Seal checks presence and does not call a Proc. " \
+                "Required when a push-capable type is registered and the Expo adapter is not disabled.",
+          allowed: [String, Proc, NilClass],
+          default: nil
+
+        add_composer :self_test_deep_link,
+          desc: "Deep link for the account push self-test. String or zero-argument Proc. " \
+                "Resolved only when SendSelfTest runs. Blank fails the test before Produce.",
+          allowed: [String, Proc, NilClass],
+          default: nil
+
+        add_composer :interruption_levels,
+          desc: "Urgency levels this host's shipped iOS binary can honor, as Expo `interruptionLevel`. " \
+                "Subset of normal, time_sensitive, critical. `normal` is always supported. A declared " \
+                "urgency above this set degrades critical -> time_sensitive -> normal. Add `time_sensitive` " \
+                "only after the binary carries the Time Sensitive capability, and `critical` only with " \
+                "Apple's Critical Alerts entitlement. Default normal only.",
+          allowed: Array,
+          default: ["normal"],
+          default_shown: '["normal"]',
+          validator: ->(val) { val.all? { |level| INTERRUPTION_LEVELS.include?(level) } },
+          invalid_message: ->(val) { "Provided #{val.inspect}. Allowed levels: #{INTERRUPTION_LEVELS.join(', ')}" }
+
+        def home_deep_link_configured?
+          link_configured?(home_deep_link)
+        end
+
+        def resolve_home_deep_link
+          resolve_link(home_deep_link)
+        end
+
+        def self_test_deep_link_configured?
+          link_configured?(self_test_deep_link)
+        end
+
+        def resolve_self_test_deep_link
+          resolve_link(self_test_deep_link)
+        end
+
+        private
+
+        def link_configured?(value)
+          return true if value.respond_to?(:call)
+          return false unless value.is_a?(String)
+
+          !value.strip.empty?
+        end
+
+        def resolve_link(value)
+          resolved = value.respond_to?(:call) ? value.call : value
+          return nil unless resolved.is_a?(String)
+
+          stripped = resolved.strip
+          stripped.empty? ? nil : stripped
+        end
       end
     end
   end

data/lib/command_tower/install/baseline.rb

@@ -18,6 +18,8 @@ module CommandTower
         20260906180000_create_user_experience_states.rb
         20261010000001_add_inbox_presentation_snapshot_to_messaging_communications.rb
         20261010000002_add_conversation_identity_to_messaging_communications.rb
+        20261012000001_add_provider_metadata_to_messaging_delivery_attempts.rb
+        20261012000002_add_finished_at_index_to_messaging_delivery_attempts.rb
       ].freeze
 
       module_function

data/lib/command_tower/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: command_tower
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - matt-taylor
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-10-11 00:00:00.000000000 Z
+date: 2026-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phonelib
@@ -275,6 +275,7 @@ files:
 - app/errors/command_tower/errors/account/phone_verification_throttled_error.rb
 - app/errors/command_tower/errors/account/push_capability_unavailable_error.rb
 - app/errors/command_tower/errors/account/push_endpoint_not_found_error.rb
+- app/errors/command_tower/errors/account/push_test_destination_error.rb
 - app/errors/command_tower/errors/account/push_test_no_endpoint_error.rb
 - app/errors/command_tower/errors/account/push_test_rate_limit_error.rb
 - app/errors/command_tower/errors/account/pushover_already_configured_error.rb
@@ -503,7 +504,9 @@ files:
 - app/services/command_tower/messaging/execution/adapters/email/configuration.rb
 - app/services/command_tower/messaging/execution/adapters/expo/adapter.rb
 - app/services/command_tower/messaging/execution/adapters/expo/configuration.rb
+- app/services/command_tower/messaging/execution/adapters/expo/endpoint_ticket_history.rb
 - app/services/command_tower/messaging/execution/adapters/expo/http_client.rb
+- app/services/command_tower/messaging/execution/adapters/expo/interruption_level.rb
 - app/services/command_tower/messaging/execution/adapters/fake_adapter.rb
 - app/services/command_tower/messaging/execution/adapters/pushover/adapter.rb
 - app/services/command_tower/messaging/execution/adapters/pushover/configuration.rb
@@ -514,6 +517,7 @@ files:
 - app/services/command_tower/messaging/execution/adapters/unconfigured_adapter.rb
 - app/services/command_tower/messaging/execution/attempt_ledger.rb
 - app/services/command_tower/messaging/execution/claim.rb
+- app/services/command_tower/messaging/execution/expo_receipt_collection.rb
 - app/services/command_tower/messaging/execution/invalid_adapter_contract_error.rb
 - app/services/command_tower/messaging/execution/operation_logger.rb
 - app/services/command_tower/messaging/execution/readiness_terminal_mapping.rb
@@ -549,6 +553,7 @@ files:
 - app/services/command_tower/messaging/notification_types/error.rb
 - app/services/command_tower/messaging/notification_types/invalid_declaration_error.rb
 - app/services/command_tower/messaging/notification_types/not_found_error.rb
+- app/services/command_tower/messaging/notification_types/permitted_choice.rb
 - app/services/command_tower/messaging/notification_types/registry.rb
 - app/services/command_tower/messaging/notification_types/sealed_registry_error.rb
 - app/services/command_tower/messaging/planner.rb
@@ -567,6 +572,7 @@ 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/effective_choice.rb
 - app/services/command_tower/messaging/preferences/error.rb
 - app/services/command_tower/messaging/preferences/evaluation_result.rb
 - app/services/command_tower/messaging/preferences/evaluator.rb
@@ -601,12 +607,14 @@ files:
 - app/services/command_tower/messaging/rendering/inbox_document_renderer.rb
 - app/services/command_tower/messaging/rendering/inbox_presentation_resolver.rb
 - app/services/command_tower/messaging/rendering/inbox_presentation_snapshot.rb
+- app/services/command_tower/messaging/rendering/push_presentation.rb
 - app/services/command_tower/messaging/rendering/render_error.rb
 - app/services/command_tower/messaging/rendering/rendered_payload.rb
 - app/services/command_tower/messaging/rendering/rendered_push_payload.rb
 - app/services/command_tower/messaging/rendering/rendered_pushover_payload.rb
 - app/services/command_tower/messaging/rendering/rendered_sms_payload.rb
 - app/services/command_tower/messaging/rendering/template_resolver.rb
+- app/services/command_tower/messaging/sound_catalog.rb
 - app/services/command_tower/secrets.rb
 - app/services/command_tower/secrets/cleanse.rb
 - app/services/command_tower/secrets/generate.rb
@@ -800,6 +808,8 @@ files:
 - db/migrate/20260906180000_create_user_experience_states.rb
 - db/migrate/20261010000001_add_inbox_presentation_snapshot_to_messaging_communications.rb
 - db/migrate/20261010000002_add_conversation_identity_to_messaging_communications.rb
+- db/migrate/20261012000001_add_provider_metadata_to_messaging_delivery_attempts.rb
+- db/migrate/20261012000002_add_finished_at_index_to_messaging_delivery_attempts.rb
 - docs/admin_workspace.md
 - docs/api_reference.md
 - docs/architecture.md
@@ -849,6 +859,7 @@ files:
 - docs/upgrades/0.16.0.md
 - docs/upgrades/0.17.0.md
 - docs/upgrades/0.18.0.md
+- docs/upgrades/0.19.0.md
 - docs/upgrades/README.md
 - lib/command_tower.rb
 - lib/command_tower/admin_scope.rb