chats 0.1.1 → 0.6.2

data/lib/chats/models/concerns/messager.rb

@@ -10,13 +10,101 @@ module Chats
   #
   #   alice.message!(bob, "hola!")               # DM in one line
   #   alice.message!(conversation, "hola!")      # or into a conversation
+  #   alice.message!(bob, "Let's play!",         # with a button under it
+  #                  action: { label: "Join my room", url: "/play/abcd" })
   #
   #   alice.chats                                # her inbox, newest first
   #   alice.unread_chats_count                   # for the nav badge
   module Messager
     extend ActiveSupport::Concern
 
+    # What `acts_as_messager` declares about a messager class. The defaults
+    # are exactly 0.1.x behaviour, so a bare `acts_as_messager` is unchanged.
+    DEFAULT_CHAT_OPTIONS = {
+      notifications: true,
+      blockable: true,
+      inbox: :default,
+      group_path: nil,
+      verified: false
+    }.freeze
+
+    INBOX_MODES = %i[default grouped].freeze
+
+    # Validate + freeze the macro's options, failing at BOOT with a plain
+    # English message rather than at 3am with a NoMethodError.
+    def self.normalize_options(notifications:, blockable:, inbox:, group_path:, verified: false)
+      inbox = inbox.to_sym
+      unless INBOX_MODES.include?(inbox)
+        raise Chats::ConfigurationError,
+              "acts_as_messager inbox: must be one of #{INBOX_MODES.inspect}, got #{inbox.inspect}"
+      end
+
+      if group_path && !group_path.respond_to?(:call)
+        raise Chats::ConfigurationError,
+              "acts_as_messager group_path: must respond to #call (a proc/lambda), got #{group_path.inspect}"
+      end
+
+      # Deliberately STRICTER than its boolean neighbours, which coerce with
+      # `!!`. "Official account" is a trust claim shown to everyone who talks
+      # to this messager, so `verified: "false"` (an ENV var, a YAML
+      # round-trip) has to fail at boot rather than quietly verify it.
+      unless [true, false].include?(verified)
+        raise Chats::ConfigurationError,
+              "acts_as_messager verified: must be true or false, got #{verified.inspect}"
+      end
+
+      {
+        notifications: !!notifications,
+        blockable: !!blockable,
+        inbox: inbox,
+        group_path: group_path,
+        verified: verified
+      }.freeze
+    end
+
+    class_methods do
+      # True unless declared with `acts_as_messager notifications: false`.
+      def chat_notifications?
+        chat_options[:notifications]
+      end
+
+      # True unless declared with `acts_as_messager blockable: false`.
+      def chat_blockable?
+        chat_options[:blockable]
+      end
+
+      # :default | :grouped (see Chats::Inbox).
+      def chat_inbox_mode
+        chat_options[:inbox]
+      end
+
+      # Whether every direct conversation with this messager folds into ONE
+      # inbox row (see Chats::InboxGroup).
+      def chat_grouped_inbox?
+        chat_inbox_mode == :grouped
+      end
+
+      # The `group_path:` callable, or nil (then the stacked row links to the
+      # filtered inbox).
+      def chat_group_path
+        chat_options[:group_path]
+      end
+
+      # True when declared with `acts_as_messager verified: true` — an
+      # OFFICIAL account (a support desk, an organization, a brand). The
+      # bundled views badge its name wherever they show it.
+      def chat_verified?
+        chat_options[:verified]
+      end
+    end
+
     included do
+      # Declared by `acts_as_messager`; a plain `include Chats::Messager`
+      # gets the defaults. class_attribute so STI subclasses inherit it.
+      class_attribute :chat_options,
+                      instance_accessor: false,
+                      default: Chats::Messager::DEFAULT_CHAT_OPTIONS
+
       has_many :chat_participations,
                class_name: "Chats::Participant",
                as: :messager,
@@ -63,30 +151,58 @@ module Chats
     #   alice.message!(bob, "are you coming?")
     #   alice.message!(bob, "about the ride", about: ride)
     #   alice.message!(conversation, "hi all!", files: [photo])
-    def message!(target, body = nil, about: nil, files: [], reply_to: nil)
+    #
+    # `author:` is the human (or bot) writing on the SENDER's behalf — an
+    # agent answering from a support desk seat. It signs the bubble; the
+    # sender stays the conversation identity. See Chats::Message#signed?.
+    #
+    #   desk.message!(alice, "On it!", author: lucia)
+    #
+    # `action:` is the one featured button under the words — a label and a
+    # url (see Chats::Action). It rides on a message the body rules already
+    # accept; an action alone is not a message.
+    #
+    #   alice.message!(bob, "Let's play!", action: { label: "Join my room", url: room_path(room) })
+    def message!(target, body = nil, about: nil, files: [], reply_to: nil, author: nil, action: nil)
       conversation =
         case target
         when Chats::Conversation then target
         else chat_with(target, about: about)
         end
 
-      attributes = { sender: self, body: body, reply_to: reply_to }
+      attributes = { sender: self, body: body, reply_to: reply_to, author: author, action: action }
       attributes[:files] = files if files.present?
       conversation.messages.create!(**attributes)
     end
 
     # The inbox: every active conversation, blocked counterparts hidden,
-    # newest activity first. A relation — chain `.limit`, `.includes`, etc.
+    # `config.inbox_scope` applied, newest activity first. A relation —
+    # chain `.limit`, `.includes`, etc.
+    #
+    # THE one definition of "what is in this messager's inbox": the inbox
+    # screen, the unread count, the live badge and a host's own queries all
+    # read it, so a conversation the scope hides is hidden everywhere. Until
+    # 0.4.1 the badge counted through the raw `inbox_for` relation and could
+    # light up for a conversation the inbox would never show.
+    #
+    # It is also the AUTHORIZATION relation (every engine lookup is
+    # `viewer.chats.find(id)`), which is why it includes conversations
+    # with no messages yet: the thread you just opened must open. The
+    # lists narrow it with `Chats::Conversation.with_messages` (see
+    # Chats::Inbox); `chats.with_messages` is what your own lists want too.
     def chats
-      Chats::Conversation.inbox_for(self)
+      relation = Chats::Conversation.inbox_for(self)
+      Chats.config.inbox_scope.call(relation, self) || relation
     end
 
     # Number of conversations with unread messages (the WhatsApp-style nav
     # badge counts conversations, not messages — 47 unread messages in one
     # thread is still "1 thing to deal with").
     def unread_chats_count
-      # reorder(nil): the inbox scope orders by a COALESCE expression, which
-      # PostgreSQL rejects inside a COUNT(DISTINCT …) aggregate.
+      # No `with_messages` needed to agree with the inbox: `unread_by` joins
+      # the messages, so a conversation with no messages can never be
+      # counted. reorder(nil): the inbox scope orders by a COALESCE
+      # expression, which PostgreSQL rejects inside a COUNT(DISTINCT …).
       chats.unread_by(self).reorder(nil).distinct.count
     end
 

data/lib/chats/models/conversation.rb

@@ -59,6 +59,41 @@ module Chats
       order(Arel.sql("COALESCE(chats_conversations.last_message_at, chats_conversations.created_at) DESC"))
     }
 
+    # Conversations that have at least one message, system messages and
+    # tombstones included (`last_message_id` set). Not "a person wrote here":
+    # a conversation holding only a system note, or only a deleted message,
+    # has messages. A conversation exists from the moment it is OPENED
+    # (`chat_with`, the Message button), and nobody wants an inbox full of
+    # the threads they opened and never used — "No messages yet" rows. So
+    # every LIST the gem renders (the inbox, its stacks, search, the
+    # `?with=` view, the dock's recent list) reads through this scope, while
+    # the authorization relation (`Messager#chats`) does NOT: an empty
+    # conversation still opens when addressed directly, which is how its
+    # first message gets written.
+    #
+    # Free, because the denormalized pointer already says it: a conversation
+    # has a last message exactly when it has messages (the pointer is set on
+    # every create and healed on every hard delete; a soft-deleted tombstone
+    # is still a message, so a thread whose only message was deleted stays
+    # listed, like everywhere else).
+    scope :with_messages, -> { where.not(last_message_id: nil) }
+
+    # Conversations a messager wrote in, and their complement. A narrower
+    # question than `with_messages`, which counts every message: a system
+    # line is the app talking ("Your ride was cancelled", which the inbox
+    # rightly lists), and a tombstone no longer says anything. These count
+    # only Chats::Message.human, what is left when both are set aside. For
+    # the readers that must not count a thread holding only "Alice joined":
+    # ops walls, moderation lists, analytics.
+    #
+    # One correlated EXISTS / NOT EXISTS, so they compose with any other
+    # scope (`alice.chats`, `inbox_for`, `about`, `unread_by`,
+    # `with_messages`) and never multiply rows:
+    #   alice.chats.with_human_messages
+    #   Chats::Conversation.about(ride).without_human_messages.count   # admin-wide
+    scope :with_human_messages, -> { where(human_messages_exist) }
+    scope :without_human_messages, -> { where.not(human_messages_exist) }
+
     # A messager's inbox: every conversation they're an active participant of
     # (not left), minus direct threads with someone they're blocked with,
     # newest activity first. THE hot query — keep it composable and indexed.
@@ -114,6 +149,8 @@ module Chats
     # mechanism. https://api.rubyonrails.org/classes/ActiveRecord/Relation.html#method-i-create_or_find_by
     validate :groups_must_be_enabled, if: :group?
 
+    after_create_commit -> { Chats.notify(:conversation_created, conversation: self) }
+
     # --- Finding & creating ---------------------------------------------------
 
     class << self
@@ -133,16 +170,17 @@ module Chats
         raise Chats::BlockedError, "messagers are blocked" if Chats.blocked_between?(a, b)
         raise Chats::NotAllowedError, "policy forbids messaging" unless Chats.can_message?(a, b)
 
-        conversation = create_or_find_by!(direct_key: direct_key_for([a, b], subject: about)) do |c|
-          c.kind = "direct"
-          c.subject = about
+        transaction do
+          conversation = create_or_find_by!(direct_key: direct_key_for([a, b], subject: about)) do |c|
+            c.kind = "direct"
+            c.subject = about
+          end
+          # Keep the roster in the creation transaction: the after-commit
+          # event must describe a complete conversation, including under an
+          # outer host transaction or a failed participant insertion.
+          [a, b].each { |messager| conversation.add_participant!(messager) }
+          conversation
         end
-
-        # `create_or_find_by!` may have FOUND a conversation created a moment
-        # ago by the other side — participants are ensured idempotently
-        # either way (their own unique index makes this race-safe too).
-        [a, b].each { |messager| conversation.add_participant!(messager) }
-        conversation
       end
 
       # Create a group conversation. +others+ excludes the creator (who joins
@@ -159,10 +197,10 @@ module Chats
         raise ArgumentError, "a group needs at least 2 other participants" if others.size < 2
 
         transaction do
-          conversation = create!(kind: "group", title: title, subject: about)
-          conversation.add_participant!(creator, role: "owner")
-          others.each { |messager| conversation.add_participant!(messager) }
-          conversation
+          created = create!(kind: "group", title: title, subject: about)
+          created.add_participant!(creator, role: "owner")
+          others.each { |messager| created.add_participant!(messager) }
+          created
         end
       end
 
@@ -187,6 +225,20 @@ module Chats
                            .group("chats_conversations.id")
                            .count("chats_messages.id")
       end
+
+      # EXISTS (SELECT 1 FROM chats_messages WHERE conversation_id =
+      # chats_conversations.id AND kind = 'text' AND deleted_at IS NULL),
+      # built from Chats::Message.human so the two definitions can never
+      # drift, and unscoped so a Message scope the caller happens to be inside
+      # never leaks in. Public only because scope bodies run on the relation,
+      # which cannot reach a private class method.
+      def human_messages_exist # :nodoc:
+        messages = Chats::Message.arel_table
+        Chats::Message.unscoped.human
+                      .where(messages[:conversation_id].eq(arel_table[:id]))
+                      .select(Arel.sql("1"))
+                      .arel.exists
+      end
     end
 
     # --- Predicates & lookups -------------------------------------------------
@@ -212,13 +264,30 @@ module Chats
       )
     end
 
+    # The OTHER messager in a direct thread, from +viewer+'s seat — nil for a
+    # group, and nil for a direct thread whose other seat has left. The one
+    # place the counterpart is resolved, so the title, the avatar and the
+    # verified badge on an inbox row always name the same person.
+    #
+    # Memoized per viewer: an inbox row asks for it two or three times, and a
+    # row that cost one query in 0.2.0 must not start costing three.
+    def counterpart_for(viewer)
+      return nil unless direct?
+
+      @counterparts ||= {}
+      key = viewer && Chats.messager_key(viewer)
+      return @counterparts[key] if @counterparts.key?(key)
+
+      @counterparts[key] = other_participants(viewer).includes(:messager).first&.messager
+    end
+
     # What this conversation is called from +viewer+'s seat: a direct thread
     # is named after the counterpart; a group after its title (or its
     # members, when untitled).
     def title_for(viewer)
       if direct?
-        other = other_participants(viewer).includes(:messager).first
-        other ? Chats.display_name_for(other.messager) : I18n.t("chats.conversation.empty_title")
+        other = counterpart_for(viewer)
+        other ? Chats.display_name_for(other) : I18n.t("chats.conversation.empty_title")
       else
         title.presence || participants.active.includes(:messager).limit(4).map do |p|
           Chats.display_name_for(p.messager)
@@ -235,6 +304,31 @@ module Chats
       subject.try(:chat_subject_label) || "#{subject.class.model_name.human} #{subject.id}"
     end
 
+    # Whether new messages are refused here, decided by the SUBJECT (see
+    # Chats::ChatSubject#chat_locked?). A subjectless conversation is never
+    # locked. Reading is never affected — only sending.
+    def locked?
+      return false if subject.nil?
+
+      subject.try(:chat_locked?) || false
+    end
+
+    # The host's explanation for the lock, or the gem's localized fallback.
+    # Always a sentence worth showing: a locked composer that says nothing is
+    # indistinguishable from a broken one.
+    def locked_notice
+      return nil unless locked?
+
+      subject.try(:chat_locked_notice).presence || I18n.t("chats.composer.locked")
+    end
+
+    # The guard every write that ISN'T a message itself calls (reactions
+    # today). Message writes go through Chats::Message#refuse_when_locked!,
+    # which exempts system messages.
+    def refuse_writes_when_locked! # :nodoc:
+      raise Chats::LockedError.new(conversation: self) if locked?
+    end
+
     # --- Membership -----------------------------------------------------------
 
     # Idempotent, race-safe membership. Re-adding someone who left re-joins
@@ -250,14 +344,46 @@ module Chats
       participant
     end
 
+    # Recompute the deterministic identity of a DIRECT thread after its
+    # roster changed (see Chats::Participant#reseat!). Without this the key
+    # would still name the old pair, and `chat_with` would open a SECOND
+    # thread for the new one. No-op for groups (they have no key).
+    def reindex_direct_key! # :nodoc:
+      return self unless direct?
+
+      # `reset`: the caller just changed a seat, and a participants
+      # association loaded BEFORE that would name the old pair.
+      messagers = participants.reset.includes(:messager).filter_map(&:messager)
+      return self unless messagers.size == 2
+
+      update_columns(
+        direct_key: self.class.direct_key_for(messagers, subject: subject),
+        updated_at: Time.current
+      )
+      self
+    end
+
     # --- Messaging ------------------------------------------------------------
 
     # Post a message from your APP into the conversation — "Your ride was
     # cancelled", "Payment received" — rendered as a centered system note,
     # not a bubble. This is the stable entry point notification systems
     # (e.g. a Noticed delivery method) should call.
-    def post_system_message!(body)
-      messages.create!(kind: "system", body: body)
+    #
+    # `action:` puts a button under the note (see Chats::Action):
+    #
+    #   conversation.post_system_message!("Your ride was cancelled",
+    #                                     action: { label: "Book another", url: "/rides/new" })
+    def post_system_message!(body, action: nil)
+      messages.create!(kind: "system", body: body, action: action)
+    end
+
+    # The newest thing a messager wrote here (see `.with_human_messages`), or
+    # nil when none did. Unlike +last_message+ it skips system lines and
+    # tombstones, and it is a query, not the denormalized pointer: one per
+    # call. For a list, batch it with Chats::Message.last_human_in(conversations).
+    def last_human_message
+      messages.human.recent_first.first
     end
 
     # --- Read state -----------------------------------------------------------
@@ -323,11 +449,19 @@ module Chats
       field.to_s == "title" && title.present?
     end
 
+    # Whether anything was removed (see Chats::Message#remove_reported_field!):
+    # false for a title already gone, decided under the row lock.
     def remove_reported_field!(field)
       return false unless field.to_s == "title"
 
-      update!(title: nil)
-      true
+      with_lock do
+        next false if title.blank?
+
+        update!(title: nil)
+        true
+      end
+    rescue ActiveRecord::RecordNotFound
+      false
     end
 
     def report_visible_to?(viewer, field: nil)