chats 0.1.1 → 0.3.1

data/lib/chats.rb

@@ -6,6 +6,7 @@ require "global_id"
 require_relative "chats/version"
 require_relative "chats/errors"
 require_relative "chats/configuration"
+require_relative "chats/subscribers"
 require_relative "chats/macros"
 
 require_relative "chats/engine" if defined?(::Rails::Engine)
@@ -24,6 +25,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 +51,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 +133,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 +177,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 +267,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_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,
@@ -103,6 +109,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 +149,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 +162,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,12 @@ 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
+  #
   # Encrypt message bodies at rest (ActiveRecord Encryption; requires
   # `bin/rails db:encryption:init`). Body search degrades when enabled.
   #
@@ -80,6 +102,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 +142,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 +184,47 @@ 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/_locked_composer.html.erb           the locked composer's body
+  #   app/views/chats/slots/_message_meta.html.erb              after each bubble's timestamp
+  #
+  # `rails generate chats:views` is still there for wholesale restyling.
 end

data/lib/generators/chats/upgrade_generator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module Chats
+  module Generators
+    # `rails generate chats:upgrade` — copy the migrations a version bump
+    # needs into an EXISTING install. Nothing else: the initializer, the
+    # views and the routes you already own stay untouched.
+    #
+    # Currently writes the 0.2.0 migration (message authorship). It is
+    # written guarded, so running it against an install that already has the
+    # columns (a fresh 0.2.0 install) is a no-op rather than an error.
+    class UpgradeGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Add the migrations a chats version bump needs (0.2.0: message authorship)"
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_author_migration
+        migration_template "add_author_to_chats_messages.rb.erb",
+                           File.join(db_migrate_path, "add_author_to_chats_messages.rb")
+      end
+
+      def display_post_upgrade_message
+        say "\n💬 chats upgrade migrations copied.", :green
+        say "\n  1. Run 'rails db:migrate'."
+        say "  2. New in 0.2.0 — all opt-in, nothing changes until you ask:"
+        say "       acts_as_messager notifications: false, blockable: false, inbox: :grouped"
+        say "       Chats.on(:message_created) { |message| … }   # replaces config.notifier"
+        say "       config.messager_url / config.message_signature / config.inbox_scope"
+        say "       chat_locked? / chat_locked_notice on your chat subjects"
+        say "  3. See the CHANGELOG for the full list.\n", :green
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: chats
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.1
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-06-10 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -135,8 +135,11 @@ files:
 - app/helpers/chats/engine_helper.rb
 - app/javascript/chats/composer_controller.js
 - app/javascript/chats/debounced_submit_controller.js
+- app/javascript/chats/refresh_inbox_controller.js
 - app/javascript/chats/thread_controller.js
 - app/views/chats/conversations/_conversation_row.html.erb
+- app/views/chats/conversations/_group.html.erb
+- app/views/chats/conversations/_locked_composer.html.erb
 - app/views/chats/conversations/_messages_page.html.erb
 - app/views/chats/conversations/_read_state.html.erb
 - app/views/chats/conversations/index.html.erb
@@ -146,11 +149,14 @@ files:
 - app/views/chats/messages/_message.html.erb
 - app/views/chats/messages/create.turbo_stream.erb
 - app/views/chats/messages/errors.turbo_stream.erb
+- app/views/chats/messages/locked.turbo_stream.erb
 - app/views/chats/shared/_unread_badge.html.erb
+- app/views/chats/shared/_verified_badge.html.erb
 - config/importmap.rb
 - config/locales/en.yml
 - config/locales/es.yml
 - config/routes.rb
+- context7.json
 - docs/PRD.md
 - docs/campfire_review.md
 - gemfiles/rails_7.1.gemfile
@@ -161,6 +167,8 @@ files:
 - lib/chats/configuration.rb
 - lib/chats/engine.rb
 - lib/chats/errors.rb
+- lib/chats/inbox.rb
+- lib/chats/inbox_group.rb
 - lib/chats/macros.rb
 - lib/chats/models/application_record.rb
 - lib/chats/models/concerns/chat_subject.rb
@@ -169,10 +177,13 @@ files:
 - lib/chats/models/message.rb
 - lib/chats/models/participant.rb
 - lib/chats/models/reaction.rb
+- lib/chats/subscribers.rb
 - lib/chats/version.rb
 - lib/generators/chats/install_generator.rb
+- lib/generators/chats/templates/add_author_to_chats_messages.rb.erb
 - lib/generators/chats/templates/create_chats_tables.rb.erb
 - lib/generators/chats/templates/initializer.rb
+- lib/generators/chats/upgrade_generator.rb
 - lib/generators/chats/views_generator.rb
 homepage: https://github.com/rameerez/chats
 licenses: