chats 0.1.1 → 0.6.2

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.6.2"
 end

data/lib/chats.rb

@@ -6,6 +6,8 @@ require "global_id"
 require_relative "chats/version"
 require_relative "chats/errors"
 require_relative "chats/configuration"
+require_relative "chats/subscribers"
+require_relative "chats/send_rate_limited"
 require_relative "chats/macros"
 
 require_relative "chats/engine" if defined?(::Rails::Engine)
@@ -24,6 +26,8 @@ require_relative "chats/engine" if defined?(::Rails::Engine)
 #   user.chat_with(other)              # find-or-create a direct conversation
 #   user.message!(other, "hello!")     # ...and say something in one line
 #
+#   Chats.on(:message_created) { |m| } # subscribe to the domain moments
+#
 # Everything else (controllers, views, broadcasts) ships with the engine and
 # is overridable the Devise way (`rails g chats:views`).
 module Chats
@@ -48,9 +52,16 @@ module Chats
       @config = Configuration.new
       @messager_classes = nil
       @subject_classes = nil
+      reset_subscribers!
       self
     end
 
+    # The gem's own deprecator (registered with `Rails.application.deprecators`
+    # by the engine, so `config.active_support.deprecation` governs it).
+    def deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new("1.0", "chats")
+    end
+
     # --- Registries -----------------------------------------------------------
     #
     # `acts_as_messager` / `acts_as_chat_subject` self-register the calling
@@ -123,23 +134,34 @@ module Chats
       config.can_message.call(sender, recipient)
     end
 
-    # Fire a domain event through the host's notifier hook (no-op by default).
-    # Events (see Chats::Configuration#notifier):
-    #   :message_created      message:      (every persisted, non-system message)
-    #   :participant_added    participant:  (someone added to a group)
+    # --- Events ---------------------------------------------------------------
+
+    # Subscribe to a domain moment. Many subscribers per event; each one runs
+    # isolated, so a raising subscriber is reported and the others still run.
+    #
+    #   Chats.on(:message_created)      { |message| }
+    #   Chats.on(:conversation_created) { |conversation| }
+    #   Chats.on(:participant_left)     { |participant| }
+    #   Chats.on(:conversation_read)    { |conversation:, participant:| }
     #
-    # Hosts typically point this at a Noticed notifier or a mailer job:
-    #   config.notifier = ->(event, **payload) {
-    #     NewMessageNotifier.with(**payload).deliver if event == :message_created
-    #   }
+    # Pass `key:` from reloadable code (a `to_prepare` block): re-registering
+    # the same key REPLACES the previous subscriber instead of stacking a
+    # duplicate on every code reload.
+    def on(event, key: nil, &block)
+      Subscribers.on(event, key: key, &block)
+    end
+
+    # Drop every `Chats.on` registration (also called by `reset!`).
+    def reset_subscribers!
+      Subscribers.reset!
+      self
+    end
+
+    # Fire a domain event at every subscriber (see Chats.on). Error-isolated:
+    # a broken subscriber must never break message delivery itself — the
+    # message is already committed; notifications are best-effort fan-out.
     def notify(event, **payload)
-      config.notifier.call(event, **payload)
-    rescue StandardError => e
-      # A broken notifier must never break message delivery itself — the
-      # message is already committed; notifications are best-effort fan-out.
-      # Same error-isolation philosophy as pricing_plans' lifecycle callbacks.
-      logger&.error("[chats] notifier raised on #{event}: #{e.class}: #{e.message}")
-      nil
+      Subscribers.emit(event, **payload)
     end
 
     # --- Display helpers (used by the bundled views) --------------------------
@@ -156,6 +178,80 @@ module Chats
       config.messager_avatar.call(messager)
     end
 
+    # Where a messager's profile lives, per `config.messager_url` (nil by
+    # default — the bundled views then render plain text, never a dead link).
+    def messager_url_for(messager)
+      return nil if messager.nil?
+
+      config.messager_url.call(messager).presence
+    end
+
+    # The signature line under a signed message ("— Lucía G."), per
+    # `config.message_signature` when the host sets one. Nil for messages
+    # that aren't signed (see Chats::Message#signed?).
+    def message_signature_for(message)
+      return nil if message.nil? || !message.signed?
+
+      if config.message_signature
+        config.message_signature.call(message).presence
+      else
+        I18n.t("chats.message.signature", name: display_name_for(message.author))
+      end
+    end
+
+    # --- Messager options (see acts_as_messager) --------------------------------
+
+    # Whether +messager+ can be notified at all. False for headless messagers
+    # declared with `acts_as_messager notifications: false` (a support desk, a
+    # bot): hosts stop branching on class in every notifier.
+    def notifications_for?(messager)
+      messager_option(messager, :chat_notifications?)
+    end
+
+    # Whether block/report affordances make sense against +messager+.
+    # False for `acts_as_messager blockable: false`.
+    def blockable?(messager)
+      messager_option(messager, :chat_blockable?)
+    end
+
+    # Whether +messager+'s direct conversations stack into one inbox row
+    # (`acts_as_messager inbox: :grouped`).
+    def grouped_inbox?(messager)
+      messager_option(messager, :chat_grouped_inbox?, default: false)
+    end
+
+    # Whether +messager+ is an OFFICIAL account (`acts_as_messager verified:
+    # true`) — a support desk, an organization, a brand. The bundled views
+    # badge its name; hosts can read it to do the same on their own screens.
+    # Defaults to false: nothing is verified until a model says so.
+    def verified?(messager)
+      messager_option(messager, :chat_verified?, default: false)
+    end
+
+    # The polymorphic type names of every registered messager class that
+    # stacks (`inbox: :grouped`). Empty in an ordinary app — which is what
+    # keeps the inbox query there byte-identical to 0.1.x. Used as a SQL
+    # PREFILTER only; whether a given counterpart actually stacks is still
+    # decided per-record by `grouped_inbox?` (STI subclasses share a
+    # polymorphic_name with siblings that may not be grouped).
+    def grouped_messager_types
+      messager_class_names.filter_map do |name|
+        klass = name.safe_constantize
+        next unless klass.respond_to?(:chat_grouped_inbox?) && klass.chat_grouped_inbox?
+
+        klass.polymorphic_name
+      end.uniq
+    end
+
+    # The signed GlobalID that scopes the inbox to conversations with
+    # +messager+ (`GET /conversations?with=…`). Purpose-scoped and
+    # non-expiring: inbox rows live on long-lived pages.
+    def inbox_with_sgid(messager)
+      return nil if messager.nil?
+
+      messager.to_sgid(expires_in: nil, for: :chats_inbox_with).to_s
+    end
+
     # --- Internals ------------------------------------------------------------
 
     def logger
@@ -172,6 +268,18 @@ module Chats
 
     private
 
+    # Ask a messager's CLASS about an `acts_as_messager` option. Duck-typed
+    # (never `is_a?`): anything that doesn't answer is treated as a stock
+    # messager, so a plain host model keeps 0.1.x behaviour.
+    def messager_option(messager, predicate, default: true)
+      return default if messager.nil?
+
+      klass = messager.is_a?(Class) ? messager : messager.class
+      return default unless klass.respond_to?(predicate)
+
+      klass.public_send(predicate)
+    end
+
     def registered_class?(registry, klass)
       klass = klass.class unless klass.is_a?(Class) || klass.is_a?(String)
       name = klass.is_a?(String) ? klass : klass.name

data/lib/generators/chats/templates/add_action_to_chats_messages.rb.erb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# chats 0.4.0 — message ACTIONS.
+#
+# A message may carry one featured button: a label and the url it opens
+# ("Your invoice is ready" → Pay now). Stored as {"label":…,"url":…} in its
+# own JSON column — `metadata` stays yours. Nullable, no default: most
+# messages have no action, and MySQL refuses defaults on JSON columns.
+# See Chats::Action.
+#
+# Safe to run on an install that already has the column (a 0.4.0 fresh
+# install does): every step is guarded, so this migration is a no-op there.
+class AddActionToChatsMessages < ActiveRecord::Migration<%= migration_version %>
+  def up
+    return if column_exists?(:chats_messages, :action)
+
+    add_column :chats_messages, :action, json_column_type
+  end
+
+  # Rolling back KEEPS the column, on purpose: this migration never removes
+  # a column it may not have added. On a fresh 0.4.0 install the create
+  # migration owns `action` and `up` above did nothing, so dropping it here
+  # would destroy every message's button with it — and nothing a migration
+  # can see records which of the two added it. A leftover nullable column
+  # is harmless to older versions of chats; drop it by hand if you mean to.
+  def down; end
+
+  private
+
+  # jsonb on every PostgreSQL adapter, like the install migration — matched
+  # by prefix because PostGIS answers "PostGIS", not "PostgreSQL".
+  def json_column_type
+    return :jsonb if connection.adapter_name.match?(/\Apostg/i)
+
+    :json
+  end
+end

data/lib/generators/chats/templates/add_author_to_chats_messages.rb.erb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# chats 0.2.0 — message AUTHORSHIP.
+#
+# `sender` is the seat a message came from; `author` is who wrote it on that
+# seat's behalf (an agent answering from a shared support desk). Both
+# nullable, both polymorphic, indexed together because they're always read
+# together. See Chats::Message#signed?.
+#
+# Safe to run on an install that already has the columns (a 0.2.0 fresh
+# install does): every step is guarded, so this migration is a no-op there.
+class AddAuthorToChatsMessages < ActiveRecord::Migration<%= migration_version %>
+  def up
+    unless column_exists?(:chats_messages, :author_type)
+      add_reference :chats_messages, :author, polymorphic: true, null: true,
+                                              type: chats_foreign_key_type, index: false
+    end
+
+    return if index_exists?(:chats_messages, [ :author_type, :author_id ], name: "index_chats_messages_on_author")
+
+    add_index :chats_messages, [ :author_type, :author_id ], name: "index_chats_messages_on_author"
+  end
+
+  def down
+    if index_exists?(:chats_messages, [ :author_type, :author_id ], name: "index_chats_messages_on_author")
+      remove_index :chats_messages, name: "index_chats_messages_on_author"
+    end
+
+    return unless column_exists?(:chats_messages, :author_type)
+
+    remove_column :chats_messages, :author_type
+    remove_column :chats_messages, :author_id
+  end
+
+  private
+
+  # Honor the host's configured primary key type (uuid vs bigint), exactly
+  # like the install migration does — the author columns must match the key
+  # type of the models they point at.
+  def chats_foreign_key_type
+    config = Rails.configuration.generators
+    config.options[config.orm][:primary_key_type] || :bigint
+  end
+end

data/lib/generators/chats/templates/create_chats_tables.rb.erb

@@ -88,6 +88,12 @@ class CreateChatsTables < ActiveRecord::Migration<%= migration_version %>
                                   foreign_key: { to_table: :chats_conversations }, index: false
       t.references :sender, polymorphic: true, null: true, type: foreign_key_type, index: false
 
+      # Who WROTE it, when that isn't the seat it was sent FROM: an agent
+      # answering from a shared support-desk seat signs the bubble while the
+      # desk stays the conversation identity. Nullable — ordinary messages
+      # have no author. See Chats::Message#signed?.
+      t.references :author, polymorphic: true, null: true, type: foreign_key_type, index: false
+
       t.string :kind, null: false, default: "text"
       t.text :body
       t.references :reply_to, type: foreign_key_type, null: true,
@@ -95,6 +101,10 @@ class CreateChatsTables < ActiveRecord::Migration<%= migration_version %>
       t.datetime :edited_at
       t.datetime :deleted_at
       t.send(json_column_type, :metadata, default: json_column_default)
+      # The one featured button a message may carry ({"label":…,"url":…}),
+      # set by the host from Ruby — see Chats::Action. Nullable with no
+      # default: most messages have none, and MySQL refuses JSON defaults.
+      t.send(json_column_type, :action)
 
       t.timestamps
     end
@@ -103,6 +113,7 @@ class CreateChatsTables < ActiveRecord::Migration<%= migration_version %>
     # (created_at, id) — see Chats::Message.before_message.
     add_index :chats_messages, [ :conversation_id, :created_at, :id ], name: "index_chats_messages_on_conversation_and_created_at"
     add_index :chats_messages, [ :sender_type, :sender_id ], name: "index_chats_messages_on_sender"
+    add_index :chats_messages, [ :author_type, :author_id ], name: "index_chats_messages_on_author"
     add_index :chats_messages, :reply_to_id, name: "index_chats_messages_on_reply_to_id"
 
     # ---------------------------------------------------------------------------
@@ -142,8 +153,12 @@ class CreateChatsTables < ActiveRecord::Migration<%= migration_version %>
     [primary_key_type, foreign_key_type]
   end
 
+  # jsonb on every PostgreSQL adapter — matched by prefix because PostGIS
+  # (activerecord-postgis-adapter) answers "PostGIS", not "PostgreSQL", and
+  # an `include?("postgresql")` check silently sent such hosts down the plain
+  # json path.
   def json_column_type
-    return :jsonb if connection.adapter_name.downcase.include?("postgresql")
+    return :jsonb if connection.adapter_name.match?(/\Apostg/i)
 
     :json
   end
@@ -151,8 +166,13 @@ class CreateChatsTables < ActiveRecord::Migration<%= migration_version %>
   # MySQL 8+ doesn't allow default values on JSON columns.
   # Returns an empty-hash default for SQLite/PostgreSQL, nil for MySQL.
   # The model handles nil metadata gracefully (attribute default {}).
+  #
+  # Trilogy is MySQL under a different ADAPTER_NAME (Rails reports "Trilogy"),
+  # so match both — a /mysql/ pattern alone hands a Trilogy host a default
+  # MySQL rejects. api_keys hit this first; see its create_api_keys_table
+  # template, which matches /mysql|trilogy/.
   def json_column_default
-    return nil if connection.adapter_name.downcase.include?("mysql")
+    return nil if connection.adapter_name.match?(/mysql|trilogy/i)
 
     {}
   end

data/lib/generators/chats/templates/initializer.rb

@@ -14,6 +14,22 @@ Chats.configure do |config|
   # Default: "User"
   config.messager_class = "User"
 
+  # Any model can converse, and a model that isn't a person can say so:
+  #
+  #   class SupportDesk < ApplicationRecord
+  #     acts_as_messager notifications: false,   # never notifiable
+  #                      blockable:     false,   # no block/report affordances
+  #                      inbox:         :grouped, # every thread with it is ONE
+  #                                               # inbox row (a "stack")
+  #                      verified:      true     # an OFFICIAL account: the
+  #                                              # views badge its name
+  #   end
+  #
+  # `group_path:` says where that stacked row goes when it holds more than
+  # one conversation (default: chats' own filtered inbox):
+  #
+  #   acts_as_messager inbox: :grouped, group_path: ->(viewer) { support_path }
+
   # ==========================================================================
   # CONTROLLER INTEGRATION
   # ==========================================================================
@@ -62,6 +78,29 @@ Chats.configure do |config|
   #
   # config.send_rate_limit = { to: 60, within: 1.minute }
   #
+  # How many conversations the inbox loads (and therefore how deep search
+  # and stacking see). The inbox is a "recent activity" surface, not an
+  # archive.
+  #
+  # config.inbox_limit = 200
+  #
+  # The messaging page's layout. :split (the default): from 700px wide,
+  # /messages is two panes, LinkedIn-style: the conversation list on the
+  # left, the open conversation on the right (/messages/:id is that same
+  # page, its conversation open); narrower, the list and the thread are
+  # separate pages. :stacked keeps them separate pages at every width.
+  # (Views you ejected with `rails g chats:views` keep rendering as they are.)
+  #
+  # config.inbox_layout = :split
+  #
+  # The messaging page's title (the bundled views give it to
+  # `content_for :title`, and the two-pane page to the tab when a row opens
+  # a conversation). nil: "Messages" / "Bob · Messages" (chats.page_title.*).
+  #
+  # config.page_title = ->(conversation, viewer) {
+  #   conversation ? "#{conversation.title_for(viewer)} | MyApp" : "Messages | MyApp"
+  # }
+  #
   # Encrypt message bodies at rest (ActiveRecord Encryption; requires
   # `bin/rails db:encryption:init`). Body search degrades when enabled.
   #
@@ -80,6 +119,23 @@ Chats.configure do |config|
   # }
   #
   # config.can_create_group = ->(creator) { creator.admin? }
+  #
+  # Composed into the inbox query before the limit — hide rows, re-scope
+  # them, whatever your product needs, without overriding the controller:
+  #
+  # config.inbox_scope = ->(relation, viewer) { relation }
+  #
+  # Whether a conversation still accepts messages is NOT a proc: the SUBJECT
+  # owns it, because the subject already owns the conversation's meaning.
+  #
+  #   class Ticket < ApplicationRecord
+  #     acts_as_chat_subject
+  #     def chat_locked?       = closed?
+  #     def chat_locked_notice = "This ticket is closed. Reply to reopen it."
+  #   end
+  #
+  # Locking gates SENDING only: the thread stays readable and the composer
+  # is replaced by the notice (see the `locked_composer` slot below).
 
   # ==========================================================================
   # TRUST & SAFETY — snap onto the `moderate` gem (or anything else)
@@ -103,25 +159,35 @@ Chats.configure do |config|
   # config.filter "Chats::Message", :body, mode: :flag
 
   # ==========================================================================
-  # NOTIFICATIONS — one hook, fan out anywhere
+  # EVENTS — subscribe to the domain moments, fan out anywhere
   # ==========================================================================
   #
-  # Called on notification-worthy domain moments. Keep it fast (enqueue jobs,
-  # don't do work inline). Events:
+  # Many subscribers per event; each runs isolated (a raising one is reported
+  # through Rails.error and never breaks message delivery). Keep them fast —
+  # enqueue jobs, don't do work inline.
   #
-  #   :message_created    message:      every persisted human message
-  #   :participant_added  participant:  someone added to a group
+  #   Chats.on(:message_created)      { |message| }       # every human message
+  #   Chats.on(:conversation_created) { |conversation| }  # a thread came into being
+  #   Chats.on(:participant_left)     { |participant| }   # someone left a group
+  #   Chats.on(:conversation_read)    { |conversation:, participant:| }
   #
   # With Noticed:
-  #   config.notifier = ->(event, **payload) {
-  #     NewMessageNotifier.with(**payload).deliver if event == :message_created
-  #   }
-  #
-  # With a plain debounced-email job (see Chats::Participant#should_notify?
-  # for the "only email once until they come back" etiquette helper):
-  #   config.notifier = ->(event, message:, **) {
-  #     ChatsUnreadEmailJob.set(wait: 10.minutes).perform_later(message) if event == :message_created
-  #   }
+  #   Chats.on(:message_created) { |message| NewMessageNotifier.with(record: message).deliver }
+  #
+  # With a debounced-email job (see Chats::Participant#should_notify? for the
+  # "only email once until they come back" etiquette helper):
+  #   Chats.on(:message_created) { |message| ChatsUnreadEmailJob.set(wait: 10.minutes).perform_later(message) }
+  #
+  # Registering from reloadable code? Pass a key, and a reload replaces the
+  # subscriber instead of stacking a second one:
+  #
+  #   Rails.application.config.to_prepare do
+  #     Chats.on(:message_created, key: :unread_email) { |message| … }
+  #   end
+  #
+  # DEPRECATED (removed in 1.0): `config.notifier = ->(event, **payload) {}`
+  # still works, but receives :message_created and :conversation_read only —
+  # the events 0.1.1 had. The ones added in 0.2.0 are Chats.on-only.
 
   # ==========================================================================
   # DISPLAY — how messagers appear in the bundled views
@@ -135,4 +201,49 @@ Chats.configure do |config|
   # config.messager_avatar = ->(messager) {
   #   messager.avatar.attached? ? messager.avatar.variant(:thumb) : nil
   # }
+  #
+  # Where a messager's profile lives. nil (the default) means the bundled
+  # views render names as plain text — chats never assumes you have a
+  # `user_path`, and never renders a dead anchor:
+  #
+  # config.messager_url = lambda do |messager|
+  #   routes = Rails.application.routes.url_helpers
+  #
+  #   case messager
+  #   when User then routes.user_path(messager)   # a desk or a bot has no profile: nil
+  #   end
+  # end
+  #
+  # The signature under a message written by an AUTHOR on a sender's behalf
+  # (`desk.message!(user, "On it!", author: agent)`). Defaults to the
+  # localized "— Agent Name":
+  #
+  # config.message_signature = ->(message) { "answered by #{message.author.first_name}" }
+  #
+  # The "official account" badge next to a `verified: true` messager's name.
+  # nil (the default) renders chats' own rosette, recoloured by the
+  # `--chats-verified` CSS variable. Set this to hand back your design
+  # system's mark instead — return html_safe markup, or nil for no badge:
+  #
+  # config.verified_badge = lambda do |messager|
+  #   ApplicationController.helpers.image_tag("official.svg", class: "badge", alt: "Official account")
+  # end
+
+  # ==========================================================================
+  # SLOTS — add one row or one button without ejecting a screen
+  # ==========================================================================
+  #
+  # The bundled views render a partial named `chats/slots/_<slot>` whenever
+  # one exists in your app. No configuration, no registration: create the
+  # file and it appears.
+  #
+  #   app/views/chats/slots/_inbox_top.html.erb                 above the first inbox row
+  #   app/views/chats/slots/_inbox_empty.html.erb               inside the empty state
+  #   app/views/chats/slots/_conversation_header_actions.html.erb  thread menu
+  #   app/views/chats/slots/_composer_actions.html.erb          your own buttons above the composer
+  #   app/views/chats/slots/_locked_composer.html.erb           the locked composer's body
+  #   app/views/chats/slots/_message_meta.html.erb              after each bubble's timestamp
+  #   app/views/chats/slots/_dock_panel_footer.html.erb         beside "See all messages" in the dock
+  #
+  # `rails generate chats:views` is still there for wholesale restyling.
 end