chats 0.1.1 → 0.3.1

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).
@@ -212,13 +222,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 +262,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 +302,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!

data/lib/chats/subscribers.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Chats
+  # The event bus behind `Chats.on`. One registry per event, many
+  # subscribers per event, each one isolated:
+  #
+  #   Chats.on(:message_created)    { |message| NewMessageNotifier.deliver(message) }
+  #   Chats.on(:conversation_read)  { |conversation:, participant:| Bell.mark_read(participant) }
+  #
+  # Two rules make this safe to use from a gem (the shape the `wallets` gem's
+  # CallbackDispatcher established):
+  #
+  #   1. A raising subscriber is REPORTED, never swallowed and never fatal —
+  #      `Rails.error.report(e, handled: true, context: { event: })` — so the
+  #      next subscriber still runs and the message still gets delivered.
+  #   2. Registration is reload-safe: pass `key:` and re-registering the same
+  #      key REPLACES the subscriber in place, so a `to_prepare` block in a
+  #      host app doesn't stack duplicates on every code reload.
+  module Subscribers
+    # Every event the gem emits, mapped to the payload key it yields
+    # POSITIONALLY to subscribers (nil = the whole payload is yielded as
+    # keywords). Registering for anything else raises at boot.
+    #
+    #   :message_created       message:                   every persisted human message
+    #   :conversation_created  conversation:              a conversation just came into being
+    #   :participant_left      participant:               someone left a group
+    #   :conversation_read     conversation:, participant: a read consumed unread content
+    EVENTS = {
+      message_created: :message,
+      conversation_created: :conversation,
+      participant_left: :participant,
+      conversation_read: nil
+    }.freeze
+
+    # The events the deprecated `config.notifier=` hook is subscribed to:
+    # exactly the two that existed in 0.1.1, and no more. A 0.1.x notifier is
+    # commonly written `->(event, message:, **)`, which would raise
+    # ArgumentError on an event that carries no `message:` — so the new
+    # events are `Chats.on` only, and an old hook keeps behaving exactly as
+    # it did.
+    LEGACY_NOTIFIER_EVENTS = %i[message_created conversation_read].freeze
+
+    # Reserved key for the subscriber `config.notifier=` registers, so
+    # re-assigning the deprecated hook replaces rather than stacks.
+    NOTIFIER_KEY = :chats_config_notifier
+
+    # One registered callable. +style+ is how it gets invoked:
+    #   :payload  the modern `Chats.on` shape (positional record, or keywords)
+    #   :event    the deprecated `config.notifier` shape — `(event, **payload)`
+    class Subscriber
+      attr_reader :key, :callable, :style
+
+      def initialize(callable, key: nil, style: :payload)
+        @callable = callable
+        @key = key
+        @style = style
+      end
+
+      # Invoke the subscriber for +event+ with the emitted +payload+ hash.
+      def call(event, payload)
+        if style == :event
+          callable.call(event, **payload)
+        elsif (positional = EVENTS[event])
+          callable.call(payload[positional])
+        else
+          callable.call(**payload)
+        end
+      end
+    end
+
+    class << self
+      # Register +block+ for +event+. Returns the Subscriber.
+      def on(event, key: nil, style: :payload, &block)
+        event = validate_event!(event)
+        raise ConfigurationError, "Chats.on(#{event.inspect}) requires a block" if block.nil?
+
+        subscriber = Subscriber.new(block, key: key, style: style)
+        replace_or_append(registry[event], subscriber)
+        subscriber
+      end
+
+      # Every subscriber registered for +event+, in registration order.
+      def for(event)
+        registry[validate_event!(event)].dup
+      end
+
+      # Run every subscriber of +event+, each isolated from the others.
+      # Returns the number of subscribers invoked.
+      #
+      # Emitting is never allowed to raise: it runs inside `after_commit`
+      # hooks, where an exception would punish a write that already
+      # succeeded. An unknown event here is a bug in the CALLER, so it is
+      # logged and skipped; `Chats.on` is where a bad event name fails loudly,
+      # at boot, where someone can fix it.
+      def emit(event, **payload)
+        event = event.to_sym
+        unless EVENTS.key?(event)
+          Chats.logger&.error("[chats] ignoring unknown event #{event.inspect}")
+          return 0
+        end
+
+        subscribers = registry[event]
+
+        subscribers.each do |subscriber|
+          subscriber.call(event, payload)
+        rescue StandardError => e
+          report(e, event)
+        end
+
+        subscribers.size
+      end
+
+      # Drop every registration (used by `Chats.reset!` and by hosts that
+      # re-register from a `to_prepare` block).
+      def reset!
+        @registry = nil
+        self
+      end
+
+      private
+
+      def registry
+        @registry ||= EVENTS.keys.index_with { [] }
+      end
+
+      def validate_event!(event)
+        event = event.to_sym
+        return event if EVENTS.key?(event)
+
+        raise ConfigurationError,
+              "unknown chats event #{event.inspect} — valid events are #{EVENTS.keys.map(&:inspect).join(", ")}"
+      end
+
+      # Keyed subscribers replace in place (same position, so ordering is
+      # stable across code reloads); keyless ones always append.
+      def replace_or_append(list, subscriber)
+        index = subscriber.key && list.index { |existing| existing.key == subscriber.key }
+        if index
+          list[index] = subscriber
+        else
+          list << subscriber
+        end
+      end
+
+      # A failing subscriber must be VISIBLE (not just logged): the host's
+      # error reporter is the one surface that pages someone.
+      def report(error, event)
+        if defined?(::Rails) && ::Rails.respond_to?(:error) && ::Rails.error
+          ::Rails.error.report(error, handled: true, context: { event: event })
+        else
+          Chats.logger&.error("[chats] subscriber raised on #{event}: #{error.class}: #{error.message}")
+        end
+      end
+    end
+  end
+end

data/lib/chats/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Chats
-  VERSION = "0.1.1"
+  VERSION = "0.3.1"
 end