command_tower 0.16.0 → 0.18.0

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

@@ -6,6 +6,9 @@ module CommandTower
       class Reader
         DEFAULT_LIMIT = 50
         MAX_LIMIT = 100
+        WINDOW_LIMIT = 5
+        WINDOW_MAX_OLDER = 2
+        OLDEST_UNREAD = "oldest_unread"
         SCOPE_INBOX = "inbox"
         SCOPE_ARCHIVED = "archived"
         ALLOWED_SCOPES = [SCOPE_INBOX, SCOPE_ARCHIVED].freeze
@@ -17,28 +20,36 @@ module CommandTower
             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
+            scoped = Scope.for_recipient(recipient_id).merge(list_scope_for(scope))
+            page_rows = entry_page_rows(scoped, limit:, offset:)
+            members = page_members(scoped, page_rows)
 
             ListResult.build(
-              items: records.map { |record| ItemResult.from_record(record) },
+              items: page_rows.map { |row| build_entry(row, members) },
               limit:,
               offset:,
-              total_count:,
+              total_count: entry_count(scoped),
+            )
+          end
+
+          def conversation(recipient_id:, key:, scope: SCOPE_INBOX, around: nil, before_id: nil, after_id: nil, limit: nil)
+            recipient_id = require_recipient_id!(recipient_id)
+            raise ValidationError, "key is required" if blank?(key)
+
+            scope = normalize_scope!(scope)
+            records = members_for_key(recipient_id:, key:, scope:)
+            raise NotFoundError, "conversation not found" if records.empty?
+
+            window = conversation_window(records, around:, before_id:, after_id:, limit:)
+            latest = records.last
+            ConversationResult.build(
+              scope:,
+              subject: latest.communication.conversation_title,
+              message_count: records.size,
+              unread_count: records.count { |record| record.viewed_at.nil? },
+              inbox_item_ids: records.map(&:id),
+              message_ids: window ? window.fetch(:message_ids) : records.map(&:id),
+              window: window&.except(:message_ids),
             )
           end
 
@@ -106,6 +117,208 @@ module CommandTower
             value
           end
 
+          def list_scope_for(scope)
+            if scope == SCOPE_ARCHIVED
+              Messaging::InboxItem.archived_list
+            else
+              Messaging::InboxItem.default_list
+            end
+          end
+
+          def entry_page_rows(scoped, limit:, offset:)
+            sql = <<~SQL.squish
+              SELECT conversation_key, inbox_item_id AS latest_id, item_created_at AS activity_at
+              FROM (
+                SELECT
+                  members.*,
+                  ROW_NUMBER() OVER (
+                    PARTITION BY entry_group
+                    ORDER BY item_created_at DESC, inbox_item_id DESC
+                  ) AS recency_rank
+                FROM (#{member_groups_sql(scoped)}) members
+              ) ranked
+              WHERE recency_rank = 1
+              ORDER BY activity_at DESC, latest_id DESC
+              LIMIT #{limit} OFFSET #{offset}
+            SQL
+
+            Messaging::InboxItem.connection.select_all(sql).to_a
+          end
+
+          def entry_count(scoped)
+            sql = <<~SQL.squish
+              SELECT COUNT(*) FROM (
+                SELECT entry_group
+                FROM (#{member_groups_sql(scoped)}) members
+                GROUP BY entry_group
+              ) entry_groups
+            SQL
+
+            Messaging::InboxItem.connection.select_value(sql).to_i
+          end
+
+          def member_groups_sql(scoped)
+            scoped.select(Arel.sql(<<~SQL.squish)).to_sql
+              messaging_inbox_items.id AS inbox_item_id,
+              messaging_inbox_items.created_at AS item_created_at,
+              messaging_communications.conversation_key AS conversation_key,
+              CASE
+                WHEN messaging_communications.conversation_key IS NULL
+                  THEN CONCAT('m:', messaging_inbox_items.id)
+                ELSE CONCAT('c:', messaging_communications.conversation_key)
+              END AS entry_group
+            SQL
+          end
+
+          def page_members(scoped, page_rows)
+            keys = page_rows.filter_map { |row| row_value(row, "conversation_key").presence }
+            standalone_ids = page_rows.filter_map do |row|
+              next if row_value(row, "conversation_key").present?
+
+              Integer(row_value(row, "latest_id"))
+            end
+            ids = standalone_ids.dup
+            if keys.any?
+              ids.concat(
+                scoped.where(messaging_communications: { conversation_key: keys }).pluck("messaging_inbox_items.id"),
+              )
+            end
+            return [] if ids.empty?
+
+            scoped.where(messaging_inbox_items: { id: ids }).includes(:communication).to_a
+          end
+
+          def build_entry(row, members)
+            latest_id = Integer(row_value(row, "latest_id"))
+            key = row_value(row, "conversation_key").presence
+            group =
+              if key
+                members.select { |member| member.communication.conversation_key == key }
+              else
+                members.select { |member| member.id == latest_id }
+              end
+            group = group.sort_by { |member| [member.created_at, member.id] }
+            latest = group.find { |member| member.id == latest_id }
+            raise InvariantError, "latest inbox member missing" if latest.nil?
+
+            conversation = key.present?
+            EntryResult.build(
+              kind: conversation ? "conversation" : "message",
+              id: conversation ? key : latest.id,
+              title: conversation ? latest.communication.conversation_title : latest.communication.title,
+              preview: conversation ? latest.communication.title : nil,
+              activity_at: latest.created_at,
+              message_count: group.size,
+              unread_count: group.count { |member| member.viewed_at.nil? },
+              inbox_item_ids: group.map(&:id),
+            )
+          end
+
+          def conversation_window(records, around:, before_id:, after_id:, limit:)
+            windowed = !around.nil? || !before_id.nil? || !after_id.nil?
+            unless windowed
+              raise ValidationError, "invalid_limit" unless limit.nil?
+
+              return
+            end
+
+            modes = [around, before_id, after_id].count { |value| !value.nil? }
+            raise ValidationError, "invalid_window" unless modes == 1
+
+            page_limit = normalize_window_limit!(limit)
+            cursor = nil
+            anchor = nil
+            slice =
+              if !around.nil?
+                anchor = resolve_anchor(records, around)
+                around_slice(records, anchor, page_limit)
+              elsif !before_id.nil?
+                cursor = find_member!(records, before_id)
+                records.select { |record| before_record?(record, cursor) }.last(page_limit)
+              else
+                cursor = find_member!(records, after_id)
+                records.select { |record| before_record?(cursor, record) }.first(page_limit)
+              end
+
+            flags = window_flags(records, slice, cursor)
+            {
+              message_ids: slice.map(&:id),
+              anchor_inbox_item_id: anchor&.id,
+              has_before: flags.fetch(:has_before),
+              has_after: flags.fetch(:has_after),
+              before_cursor: flags.fetch(:before_cursor),
+              after_cursor: flags.fetch(:after_cursor),
+            }
+          end
+
+          def resolve_anchor(records, around)
+            return records.find { |record| record.viewed_at.nil? } || records.last if around.to_s == OLDEST_UNREAD
+
+            find_member!(records, around)
+          end
+
+          def around_slice(records, anchor, limit)
+            index = records.index(anchor)
+            before_count = [WINDOW_MAX_OLDER, index, limit - 1].min
+            after_count = [limit - 1 - before_count, records.length - 1 - index].min
+            records[(index - before_count)..(index + after_count)]
+          end
+
+          def find_member!(records, inbox_item_id)
+            id = Integer(inbox_item_id)
+            records.find { |record| record.id == id } || raise(ValidationError, "invalid_cursor")
+          rescue ArgumentError, TypeError
+            raise ValidationError, "invalid_cursor"
+          end
+
+          def window_flags(records, slice, cursor)
+            if slice.any?
+              first = slice.first
+              last = slice.last
+              {
+                has_before: records.any? { |record| before_record?(record, first) },
+                has_after: records.any? { |record| before_record?(last, record) },
+                before_cursor: first.id,
+                after_cursor: last.id,
+              }
+            else
+              {
+                has_before: !cursor.nil? && records.any? { |record| before_record?(record, cursor) },
+                has_after: !cursor.nil? && records.any? { |record| before_record?(cursor, record) },
+                before_cursor: nil,
+                after_cursor: nil,
+              }
+            end
+          end
+
+          def before_record?(candidate, boundary)
+            return candidate.id < boundary.id if candidate.created_at == boundary.created_at
+
+            candidate.created_at < boundary.created_at
+          end
+
+          def normalize_window_limit!(limit)
+            value = limit.nil? ? WINDOW_LIMIT : Integer(limit)
+            raise ValidationError, "invalid_limit" if value < 1 || value > WINDOW_LIMIT
+
+            value
+          rescue ArgumentError, TypeError
+            raise ValidationError, "invalid_limit"
+          end
+
+          def members_for_key(recipient_id:, key:, scope:)
+            Scope.for_recipient(recipient_id)
+              .merge(list_scope_for(scope))
+              .includes(:communication)
+              .where(messaging_communications: { conversation_key: key })
+              .order(Arel.sql("messaging_inbox_items.created_at ASC, messaging_inbox_items.id ASC"))
+              .to_a
+          end
+
+          def row_value(row, key)
+            row[key] || row[key.to_sym]
+          end
+
           def blank?(value)
             value.nil? || (value.respond_to?(:empty?) && value.empty?) ||
               (value.is_a?(String) && value.strip.empty?)

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

@@ -13,6 +13,10 @@ module CommandTower
         Reader.show(recipient_id:, inbox_item_id:)
       end
 
+      def conversation(recipient_id:, key:, scope: Reader::SCOPE_INBOX, around: nil, before_id: nil, after_id: nil, limit: nil)
+        Reader.conversation(recipient_id:, key:, scope:, around:, before_id:, after_id:, limit:)
+      end
+
       def unread_count(recipient_id:)
         Reader.unread_count(recipient_id:)
       end

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

@@ -22,6 +22,7 @@ module CommandTower
         :retention,
         :delivery_status_visible,
         :host_ownership,
+        :inbox_document_composer,
       ) do
         def self.build(
           key:,
@@ -41,7 +42,8 @@ module CommandTower
           priority: nil,
           retention: nil,
           delivery_status_visible: nil,
-          host_ownership: nil
+          host_ownership: nil,
+          inbox_document_composer: nil
         )
           new(
             key: key.nil? ? nil : key.to_s,
@@ -62,6 +64,17 @@ module CommandTower
             retention:,
             delivery_status_visible:,
             host_ownership:,
+            # Rich Messaging Slice 2.5 revision — String class name of a
+            # pure-Ruby Inbox document composer (`.call(communication:) ->
+            # InboxDocument`), lazily `.constantize`d by
+            # `InboxDocumentRenderer` at render time, never at registration
+            # time (mirrors the existing RBAC `Entity#controller` deferred
+            # class-string convention — decouples host `to_prepare`
+            # registration order from composer class-load order). `nil`
+            # means this type intentionally has no custom Inbox document and
+            # renders via `InboxDocumentRenderer#build_generic`. See
+            # artifacts/visual-improvements/rich-messaging/authority/RICH_MESSAGING_RUBY_INBOX_DEFINITION_DISCOVERY.md.
+            inbox_document_composer: inbox_document_composer.nil? ? nil : inbox_document_composer.to_s,
           ).freeze
         end
 

data/app/services/command_tower/messaging/rendering/channel_renderer.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "erb"
 require "cgi"
 
 module CommandTower
@@ -12,7 +11,7 @@ module CommandTower
         PUSHOVER_CHANNEL = "pushover"
         PUSH_CHANNEL = "push"
         SUPPORTED_CHANNELS = [EMAIL_CHANNEL, SMS_CHANNEL, PUSHOVER_CHANNEL, PUSH_CHANNEL].freeze
-        TEMPLATE_DIR = CommandTower::Engine.root.join("app/views/command_tower/messaging/rendering")
+        TEMPLATE_FILENAME_PATTERN = /\A(?<basename>[a-z]+)\.(?<format>html|text)\.erb\z/
         DEFAULT_TITLE = "Notification"
 
         def self.render(communication:, channel_key:, recipient_address:)
@@ -120,24 +119,56 @@ module CommandTower
         alias pushover_title notification_title
 
         def render_template(filename)
-          path = TEMPLATE_DIR.join(filename)
-          raise Errno::ENOENT, "missing template #{filename}" unless path.file?
-
-          template = ERB.new(path.read, trim_mode: "-")
-          template.result_with_hash(template_locals)
+          match = TEMPLATE_FILENAME_PATTERN.match(filename.to_s)
+          raise Errno::ENOENT, "missing template #{filename}" unless match
+
+          TemplateResolver.render(
+            basename: match[:basename],
+            format: match[:format].to_sym,
+            notification_type_key: @communication.notification_type_key,
+            generic_locals: template_locals,
+            type_locals: type_template_locals,
+          )
         end
 
+        # ActionView's OutputBuffer auto-escapes any interpolated value that is
+        # not marked `html_safe?`, for every format (html and text alike) —
+        # see `ActionView::OutputBuffer#<<`. Generic templates historically
+        # relied on plain ERB, which never auto-escaped anything; callers
+        # (namely `email.html.erb`) explicitly call `h.call(...)` when they
+        # want escaping. To preserve that exact contract under ActionView
+        # rendering, `title`/`body`/`deep_link` are pre-marked `html_safe` (so
+        # raw interpolation stays unescaped, matching legacy behavior) and
+        # `h.call` marks its own already-escaped output `html_safe` too, so it
+        # is not escaped a second time by the output buffer.
         def template_locals
+          {
+            title: @communication.title.to_s.html_safe,
+            body: @communication.body.to_s.html_safe,
+            deep_link: deep_link_from_metadata&.html_safe,
+            h: ->(value) { CGI.escapeHTML(value.to_s).html_safe },
+          }
+        end
+
+        def type_template_locals
+          template_locals.merge(
+            metadata: frozen_metadata,
+            notification_type_key: @communication.notification_type_key.to_s,
+          )
+        end
+
+        def deep_link_from_metadata
           metadata = @communication.metadata
           deep_link = metadata.is_a?(Hash) ? metadata["deep_link"] || metadata[:deep_link] : nil
           deep_link = deep_link.to_s if deep_link
+          deep_link.presence
+        end
 
-          {
-            title: @communication.title.to_s,
-            body: @communication.body.to_s,
-            deep_link: deep_link.presence,
-            h: ->(value) { CGI.escapeHTML(value.to_s) },
-          }
+        def frozen_metadata
+          metadata = @communication.metadata
+          return {}.freeze unless metadata.is_a?(Hash)
+
+          metadata.to_h.transform_keys(&:to_s).freeze
         end
       end
     end

data/app/services/command_tower/messaging/rendering/inbox_document.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module CommandTower
+  module Messaging
+    module Rendering
+      # Frozen v1 Inbox content document. Rendered at read (never persisted) by
+      # `InboxDocumentRenderer`. Blocks are plain frozen Hashes, not nested
+      # `Data` objects, so `#to_h` is already the exact JSON-serializable shape
+      # the `content` response key needs — no extra conversion at the
+      # serializer boundary.
+      #
+      # This value object only guarantees the envelope (`schema` tag, `blocks`
+      # is an Array); block-level construction and validation is
+      # `InboxDocumentRenderer`'s responsibility.
+      InboxDocument = Data.define(:schema, :blocks)
+
+      # Reopened (rather than defined inside the `Data.define` block) so that
+      # `SCHEMA_V1` and `.build` attach to `InboxDocument` under normal
+      # lexical constant scoping — a block passed to `Data.define` does not
+      # change the lexical scope for constant assignment the way `class ...
+      # end` does.
+      class InboxDocument
+        SCHEMA_V1 = "inbox_document_v1"
+
+        def self.build(blocks:)
+          raise ArgumentError, "blocks must be an Array" unless blocks.is_a?(Array)
+          raise ArgumentError, "arbitrary hashes are not accepted as blocks entries" if blocks.any? { |b| !b.is_a?(Hash) }
+
+          new(schema: SCHEMA_V1, blocks: blocks.freeze).freeze
+        end
+
+        # Small pure-Ruby authoring DSL (Rich Messaging Slice 2.5 revision —
+        # replaces `inbox_document.json.erb` entirely; see
+        # artifacts/visual-improvements/rich-messaging/authority/RICH_MESSAGING_RUBY_INBOX_DEFINITION_DISCOVERY.md).
+        # A notification-type Inbox document composer calls `.compose` and
+        # authors an ordered document via exactly three methods:
+        #
+        #   doc.paragraph "..."
+        #   doc.cta "label", path: "/internal/route"
+        #   doc.cta "label", href: "https://external.example/..."
+        #   doc.presentation "pickem.make_picks", variant: :compact
+        #
+        # `cta` takes exactly one of `path:` (an internal, origin-free
+        # destination the host's own navigation owns) or `href:` (an
+        # absolute external URL opened via the platform's normal external-
+        # link handling). The composer — which already knows whether a
+        # destination is its own app's route or a third-party URL — states
+        # that intent explicitly via a typed `destination`, rather than
+        # having the frontend infer it from an absolute URL (Slice 2.6.4;
+        # see artifacts/visual-improvements/rich-messaging/plans/
+        # 2.6.4-ct-fe-inbox-navigation-capability.md).
+        # `presentation` intentionally has no `data:`/`props:` argument at
+        # all — the message type may only *name* a registered presentation
+        # capability. Its data is composed separately, post-authoring, by
+        # `InboxDocumentRenderer` and the registered presentation composer
+        # (Rich Messaging Presentation Authority §8). There is no argument
+        # slot to violate that boundary with.
+        def self.compose
+          builder = Builder.new
+          yield builder
+          build(blocks: builder.blocks)
+        end
+
+        class Builder
+          UNSAFE_SCHEMES = %w[javascript data vbscript].freeze
+          DEFAULT_CTA_LABEL = "Open"
+
+          def initialize
+            @blocks = []
+          end
+
+          def paragraph(text)
+            return self unless text.is_a?(String) && !text.empty?
+
+            @blocks << { type: "paragraph", text: }.freeze
+            self
+          end
+
+          def cta(label, path: nil, href: nil)
+            destination = cta_destination(path:, href:)
+            return self unless destination
+
+            resolved_label = label.is_a?(String) && !label.strip.empty? ? label : DEFAULT_CTA_LABEL
+            @blocks << { type: "cta", label: resolved_label, destination: }.freeze
+            self
+          end
+
+          def presentation(key, variant: nil)
+            @blocks << { type: "presentation", key: key.to_s, variant: variant&.to_s }.freeze
+            self
+          end
+
+          def blocks
+            @blocks
+          end
+
+          private
+
+          # Internal takes precedence when both are supplied — a `cta` only
+          # ever means one navigation intent, and a composer that mistakenly
+          # supplies both almost certainly means the internal one.
+          def cta_destination(path:, href:)
+            if safe_internal_path?(path)
+              { kind: "internal", path: }
+            elsif safe_href?(href)
+              { kind: "external", href: }
+            end
+          end
+
+          # A leading `//` is rejected even though it "starts with a slash" —
+          # it is a protocol-relative URL (browsers/RN resolve it against
+          # whatever scheme is active), not a safe same-app-only destination.
+          def safe_internal_path?(path)
+            path.is_a?(String) && path.start_with?("/") && !path.start_with?("//")
+          end
+
+          def safe_href?(href)
+            return false unless href.is_a?(String) && !href.strip.empty?
+
+            scheme = URI.parse(href).scheme&.downcase
+            scheme.present? && UNSAFE_SCHEMES.exclude?(scheme)
+          rescue URI::InvalidURIError
+            false
+          end
+        end
+      end
+    end
+  end
+end