chats 0.1.1 → 0.2.0

data/lib/chats/inbox_group.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Chats
+  # A stack of direct conversations that share one counterpart, shown as a
+  # SINGLE inbox row. Built by Chats::Inbox for messagers declared with
+  # `acts_as_messager inbox: :grouped` — a support desk, a marketplace
+  # storefront, any seat a person ends up with many separate threads with.
+  #
+  # It quacks like the parts of Chats::Conversation the inbox row needs
+  # (+last_message+, +last_message_at+, +unread_count+) so the two row
+  # partials stay symmetrical.
+  #
+  # +unread_count+ and +open_count+ are GLOBAL: they describe the whole
+  # stack, however deep it runs, not the bounded window in +conversations+.
+  # Chats::Inbox reads them with two indexed aggregates per stack.
+  class InboxGroup
+    # +conversations+ is the loaded WINDOW of the stack (freshest first,
+    # bounded by config.inbox_limit); +open_count+ and +unread_count+ describe
+    # the whole stack, however deep it runs.
+    attr_reader :messager, :conversations, :unread_count, :open_count
+
+    def initialize(messager:, conversations:, unread_count: 0, open_count: nil)
+      @messager = messager
+      @conversations = conversations
+      @unread_count = unread_count
+      @open_count = open_count || conversations.size
+    end
+
+    # A stack of one is really just a conversation: the row links straight to
+    # it, and the thread carries a "see all" link back to the stack.
+    def single?
+      open_count == 1
+    end
+
+    # The freshest conversation in the stack — what the row previews, and
+    # what it links to when the stack holds exactly one.
+    def conversation
+      conversations.first
+    end
+
+    # The stack's most recent message (the row's preview line).
+    def last_message
+      conversation&.last_message
+    end
+
+    # The sort key the inbox orders rows by: the freshest activity in the
+    # stack (mirrors Conversation.recent_first's COALESCE).
+    def last_message_at
+      conversations.filter_map { |c| c.last_message_at || c.created_at }.max
+    end
+
+    # Whether the stack has anything unread in it, anywhere.
+    def unread?
+      unread_count.positive?
+    end
+
+    # What the row is called. A stack is named after its counterpart from
+    # every seat, so the viewer is accepted and ignored — the signature
+    # matches Chats::Conversation#title_for so both row partials can call it.
+    def title_for(_viewer)
+      Chats.display_name_for(messager)
+    end
+
+    # Stable DOM id for the row (no AR record to derive one from).
+    def dom_id
+      "chats_inbox_group_#{messager.class.polymorphic_name.underscore.tr("/", "_")}_#{messager.id}"
+    end
+
+    # The signed, purpose-scoped GlobalID that filters the inbox to this
+    # stack (`GET /conversations?with=…`).
+    def with_sgid
+      Chats.inbox_with_sgid(messager)
+    end
+  end
+end

data/lib/chats/macros.rb

@@ -17,8 +17,31 @@ module Chats
   # lives in Chats::Messager / Chats::ChatSubject so it's discoverable,
   # testable, and `include`-able directly when a host prefers that style.
   module Macros
-    def acts_as_messager
+    # Options (all optional; the defaults are 0.1.x behaviour):
+    #
+    #   notifications: false   this messager is never notifiable — a support
+    #                          desk, a bot, an org mailbox. `Participant#
+    #                          notifiable_for?` says no, so hosts stop
+    #                          branching on class in every notifier.
+    #   blockable: false       block/report affordances don't apply to it, so
+    #                          the bundled views hide them.
+    #   inbox: :grouped        every direct conversation with this messager
+    #                          stacks into ONE inbox row (see Chats::Inbox).
+    #   group_path: ->(viewer) { }  where that stacked row links to; defaults
+    #                          to the filtered inbox (`?with=<sgid>`).
+    #
+    #   class Desk < ApplicationRecord
+    #     acts_as_messager notifications: false, blockable: false, inbox: :grouped
+    #   end
+    def acts_as_messager(notifications: true, blockable: true, inbox: :default, group_path: nil)
       include Chats::Messager
+
+      self.chat_options = Chats::Messager.normalize_options(
+        notifications: notifications,
+        blockable: blockable,
+        inbox: inbox,
+        group_path: group_path
+      )
     end
 
     def acts_as_chat_subject

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

@@ -31,5 +31,28 @@ module Chats
     def chat_subject_label
       "#{self.class.model_name.human} #{id}"
     end
+
+    # Whether conversations ABOUT this record still accept messages. The
+    # subject already owns the conversation's meaning, so it owns its
+    # openness too — a closed ticket, a delivered order, an archived listing:
+    #
+    #   class Ticket < ApplicationRecord
+    #     acts_as_chat_subject
+    #     def chat_locked?       = closed?
+    #     def chat_locked_notice = "This ticket is closed. Reply to reopen it."
+    #   end
+    #
+    # System messages are exempt (the host can always post "Ticket closed"),
+    # and locking is a WRITE rule only: the thread stays readable. See
+    # Chats::Conversation#locked?.
+    def chat_locked?
+      false
+    end
+
+    # The sentence shown where the composer would be. Nil falls back to the
+    # gem's localized "This conversation is closed."
+    def chat_locked_notice
+      nil
+    end
   end
 end

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

@@ -16,7 +16,75 @@ module Chats
   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
+    }.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:)
+      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
+
+      {
+        notifications: !!notifications,
+        blockable: !!blockable,
+        inbox: inbox,
+        group_path: group_path
+      }.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
+    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,14 +131,25 @@ 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)
+    def message!(target, body = nil, about: nil, files: [], reply_to: nil, author: nil)
+      if author && !Chats.messager_class?(author.class)
+        raise Chats::NotAllowedError,
+              "author must be a messager (acts_as_messager), got #{author.class.name}"
+      end
+
       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 }
       attributes[:files] = files if files.present?
       conversation.messages.create!(**attributes)
     end

data/lib/chats/models/conversation.rb

@@ -141,7 +141,12 @@ module Chats
         # `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).
+        # `previously_new_record?` is how we tell the two apart, so the
+        # :conversation_created event fires ONCE per conversation, not on
+        # every resume.
+        created = conversation.previously_new_record?
         [a, b].each { |messager| conversation.add_participant!(messager) }
+        Chats.notify(:conversation_created, conversation: conversation) if created
         conversation
       end
 
@@ -158,12 +163,17 @@ module Chats
         others = Array(others) - [creator]
         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
+        conversation = transaction do
+          created = create!(kind: "group", title: title, subject: about)
+          created.add_participant!(creator, role: "owner")
+          others.each { |messager| created.add_participant!(messager) }
+          created
         end
+
+        # Emitted AFTER the transaction: subscribers see a complete roster
+        # and never run inside the write that created it.
+        Chats.notify(:conversation_created, conversation: conversation)
+        conversation
       end
 
       # Deterministic identity for a direct pair (+ optional subject).
@@ -235,6 +245,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,6 +285,25 @@ 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

data/lib/chats/models/message.rb

@@ -33,6 +33,11 @@ module Chats
                inverse_of: :messages,
                counter_cache: :messages_count
     belongs_to :sender, polymorphic: true, optional: true
+    # The person (or bot) who WROTE this on the sender's behalf — an agent
+    # answering from a shared support-desk seat. The sender stays the
+    # conversation identity ("Soporte CarHey"); the author signs the bubble
+    # ("— Lucía G."). Optional, and nil for every ordinary message.
+    belongs_to :author, polymorphic: true, optional: true
     belongs_to :reply_to, class_name: "Chats::Message", optional: true
 
     has_many :reactions,
@@ -90,6 +95,8 @@ module Chats
     validate :body_must_fit_length_limit
     validate :sender_must_be_active_participant, on: :create
     validate :sender_must_not_be_blocked, on: :create
+    validate :conversation_must_not_be_locked, on: :create
+    validate :author_must_be_a_messager
     validate :files_must_be_allowed
 
     after_create :register_on_conversation
@@ -112,6 +119,19 @@ module Chats
       sender.present? && sender == messager
     end
 
+    # Written by someone OTHER than the seat it was sent from — the case a
+    # signature exists for. A message an author sent from their own seat is
+    # not "signed"; it's just theirs.
+    def signed?
+      author.present? && author != sender
+    end
+
+    # Whether +messager+ is the one who WROTE this (not necessarily the seat
+    # it was sent from).
+    def authored_by?(messager)
+      author.present? && author == messager
+    end
+
     # The body as the UI should show it (tombstones render a localized
     # "Message deleted" placeholder straight from the view, not from here —
     # this just guards against showing stale bodies by accident).
@@ -133,12 +153,19 @@ module Chats
       raise Chats::NotAllowedError, "editing is disabled" unless Chats.config.editing
       raise Chats::NotAllowedError, "can't edit a deleted message" if deleted?
 
+      refuse_when_locked!
       update!(body: new_body, edited_at: Time.current)
     end
 
     # Delete according to `config.deletion` (see class comment). Returns
     # false when deletion is disabled.
-    def soft_delete!
+    #
+    # `enforce_lock: false` is for MODERATION only (see
+    # #remove_reported_field!): a product lock must never shield reported
+    # content from removal.
+    def soft_delete!(enforce_lock: true)
+      refuse_when_locked! if enforce_lock
+
       case Chats.config.deletion
       when :soft
         transaction do
@@ -158,6 +185,16 @@ module Chats
       respond_to?(:files) && files.attached?
     end
 
+    # Every WRITE to an existing message goes through here, for the same
+    # reason `create` validates the lock: a closed conversation is closed for
+    # editing and deleting too, not just for new messages. System messages
+    # stay exempt — the app owns them.
+    def refuse_when_locked! # :nodoc:
+      return if system? || conversation.nil? || !conversation.locked?
+
+      raise Chats::LockedError.new(conversation: conversation)
+    end
+
     # --- Moderation contract (duck-typed, zero coupling) ------------------------
     #
     # Plain-Ruby methods that make a message a first-class citizen of the
@@ -167,8 +204,14 @@ module Chats
     # seams for attachment filtering. Without moderate installed they're
     # inert and cost nothing.
 
+    # Who answers for this message: its AUTHOR when it is signed, else its
+    # sender. A signed message was written by a human from a seat that is not
+    # a person — an agent answering from a support desk — and the seat cannot
+    # be the owner a moderation flag or report points at: the host's `owner`
+    # is typed to its user class, so a desk there is a type mismatch raised
+    # from inside the agent's own reply the first time a filter trips.
     def reported_owner
-      sender
+      author || sender
     end
 
     def moderation_label
@@ -189,7 +232,9 @@ module Chats
     def remove_reported_field!(field)
       return false unless field.to_s == "body"
 
-      soft_delete!
+      # Trust & Safety outranks a product lock: a closed conversation must
+      # never be a place reported content can hide.
+      soft_delete!(enforce_lock: false)
     end
 
     # Only people *in* the conversation may report a message (a message
@@ -267,6 +312,25 @@ module Chats
       errors.add(:base, :blocked) if other && Chats.blocked_between?(sender, other)
     end
 
+    # An author signs the bubble with `Chats.display_name_for`, so it has to
+    # be something that HAS a name in this system — a messager, not a ride or
+    # a listing that would render as "Listing 1".
+    def author_must_be_a_messager
+      return if author.nil? || Chats.messager_class?(author.class)
+
+      errors.add(:author, :not_a_messager)
+    end
+
+    # The subject owns the conversation's openness (Chats::ChatSubject#
+    # chat_locked?). System messages are exempt: the host must always be able
+    # to post "This ticket was closed" into the thread it just closed.
+    def conversation_must_not_be_locked
+      return if system? || conversation.nil?
+      return unless conversation.locked?
+
+      errors.add(:base, :locked)
+    end
+
     def files_must_be_allowed
       return unless respond_to?(:files)
       return unless files.attached?

data/lib/chats/models/participant.rb

@@ -105,6 +105,37 @@ module Chats
 
     def leave!
       update!(left_at: Time.current)
+      Chats.notify(:participant_left, participant: self)
+      self
+    end
+
+    # Hand this seat to a different messager, keeping the read horizon, the
+    # role and the history: the guest who signs up, the agent who takes over
+    # a shared mailbox. The MESSAGES keep their original sender — what was
+    # said was said by whoever said it.
+    #
+    # Direct conversations have their +direct_key+ recomputed, so the thread
+    # keeps resolving through `chat_with` for the NEW pair instead of
+    # stranding a duplicate.
+    def reseat!(new_messager)
+      raise ArgumentError, "reseat! requires a messager" if new_messager.nil?
+      unless Chats.messager_class?(new_messager.class)
+        raise Chats::NotAllowedError, "#{new_messager.class.name} is not a messager (acts_as_messager)"
+      end
+
+      refuse_reseat_conflicts!(new_messager)
+
+      transaction do
+        update!(messager: new_messager)
+        conversation.reindex_direct_key!
+      end
+
+      self
+    rescue ActiveRecord::RecordNotUnique
+      # The race backstop for the checks above (two reseats, or a DM opened,
+      # between the check and the write). Translated so a host never has a
+      # driver-level exception poison its transaction.
+      raise Chats::NotAllowedError, "that conversation already exists for the new pair"
     end
 
     # --- Notification etiquette (for host notifier hooks) ----------------------
@@ -114,6 +145,10 @@ module Chats
     # re-derive it: don't notify yourself, the muted, the departed — and for
     # debounced email digests, don't notify twice for the same unread burst.
     def notifiable_for?(message)
+      # Headless messagers (`acts_as_messager notifications: false`) — a
+      # support desk, a bot, an org mailbox — are never notifiable. This is
+      # THE reason hosts no longer branch on class in their notifiers.
+      return false unless Chats.notifications_for?(messager)
       return false if left? || muted?
       return false if message.sender == messager
 
@@ -135,6 +170,30 @@ module Chats
 
     private
 
+    # Everything that would make the reseat collide, checked BEFORE the
+    # write. A unique-index violation inside the transaction would abort the
+    # host's transaction too on PostgreSQL, so the pre-check is the real
+    # guard and the RecordNotUnique rescue is only the race backstop.
+    def refuse_reseat_conflicts!(new_messager)
+      if conversation.participants.where.not(id: id).exists?(
+        messager_type: new_messager.class.polymorphic_name, messager_id: new_messager.id
+      )
+        raise Chats::NotAllowedError, "that messager already has a seat in this conversation"
+      end
+
+      return unless conversation.direct?
+
+      other = conversation.other_participants(messager).includes(:messager).first&.messager
+      return if other.nil?
+
+      existing = Chats::Conversation.direct_between(new_messager, other, about: conversation.subject)
+      return if existing.nil? || existing == conversation
+
+      raise Chats::NotAllowedError,
+            "#{Chats.display_name_for(new_messager)} already has a direct conversation with " \
+            "#{Chats.display_name_for(other)}"
+    end
+
     def group_must_have_room
       return if conversation.nil? || conversation.direct?
 

data/lib/chats/models/reaction.rb

@@ -32,6 +32,11 @@ module Chats
     # toggled off. Race-safe: a concurrent double-tap resolves through the
     # unique index instead of raising.
     def self.toggle!(message:, reactor:, emoji:)
+      # Reacting is a write to the conversation, so a locked one refuses it —
+      # in BOTH directions: you can't add a reaction to a closed thread, and
+      # you can't take one back either. Same rule as editing and deleting.
+      message&.conversation&.refuse_writes_when_locked!
+
       existing = find_by(message: message, reactor: reactor, emoji: emoji)
       if existing
         existing.destroy!