chats 0.2.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c51ebc5c0e2da96363bb5b2e85d9a9c2a91e41f7ddb9d351ff10001654a48325
-  data.tar.gz: a06cde14d3953972e7061b2950b7a52c696f4292e25a2a91c9c7bb6ce7d269cb
+  metadata.gz: 80fff570dabbff3e99a5a5f37c43b43acd334a94aae30c23b8c76bfbab5441e8
+  data.tar.gz: 72efe83f785fe99876d6b5922a5d834897f1771f3880bead3b43ae6f342ba96d
 SHA512:
-  metadata.gz: 5d23c31395edb382ec05fc6b7478a4e219b1878dc29f67092451101ef720bf2df556ae92976384665c0e108ca4607557ed9d1badf0af9357143182f1fdb57e6d
-  data.tar.gz: 3f02985c90410059af142a03fc3a3298540f71fb05d9b46991f39ea22999bfab64738f86beb92db7355e98c68e7962c2b6e79925335cf409d67842c1b1a7a5eb
+  metadata.gz: 362eda363af938a99823b38d7fd4e0a5594d62d305f6a47f88a1dc9978c6556ab37561259007f1649567472a98deecff6cc96050afbbedc3d36637ee99207a84
+  data.tar.gz: aa7b170ba97de94d58b08516dbd4674905f1ab78e2bcd4a2e9af997e0aab6d71a3fc35b1aea2f6f0ab97fd02d1d6fa46494a1826f784b35184105c0c1c3c89b6

data/CHANGELOG.md

@@ -4,6 +4,85 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] - 2026-09-17
+
+### Fixed
+
+- Grouped inbox limits preserve other counterparts even when one desk has many recent conversations.
+- Conversation creation and participant departure events run after commit and remain silent on rollback. Direct conversation creation includes its roster in the transaction.
+- A message author may be any persisted model; staff need not become messagers to sign a desk's reply.
+
+### Added
+
+- `Chats::SendRateLimited`, a controller concern sharing the configured sender budget across chat and product-specific composers, using the host's cache store on all supported Rails versions.
+
+## [0.3.1] - 2026-09-16
+
+### Fixed
+- **The verified badge was a star, not a check.** 0.3.0 shipped a
+  five-pointed star as the "official account" mark, copied from a host icon
+  that was named `verified_badge` but drawn as a star. A star reads as
+  "favourite" or "rated", not "this account is really us", and at 14px a
+  solid star and a solid rosette are the same blob. It is now heroicons
+  `check-badge`: a scalloped rosette with a tick knocked out of it, which
+  is the mark people already read as verified. `fill-rule="evenodd"` is
+  what knocks the tick out — without it the rosette fills solid.
+
+## [0.3.0] - 2026-09-16
+
+Official accounts. Some counterparts are not people you met — they are a
+support desk, an organization, a shop, a brand — and a person should be able
+to tell at a glance. **Nothing changes until a model says so**: 0.2.x
+installs upgrade by bumping the gem, with no migration and no new
+configuration.
+
+### Added
+- **`acts_as_messager verified: true`.** A messager declares itself an
+  OFFICIAL account, and every bundled view that shows its name marks it: the
+  inbox row, the stacked inbox row, and the thread header. `Klass.
+  chat_verified?` is the class predicate and `Chats.verified?(messager)`
+  reads it duck-typed — false for a plain model, a nil, a non-messager — so
+  hosts can badge their own screens without a class check. The option is
+  independent of the headless ones: a desk is usually headless *and*
+  official, a shop is usually official and nothing else. Unlike its boolean
+  neighbours it refuses to coerce — `verified: "false"` raises
+  `Chats::ConfigurationError` at boot rather than quietly verifying an
+  account, because a badge is a trust claim and not a display preference.
+- **The badge itself**, `chats/shared/_verified_badge` — an inline rosette
+  that sizes itself from the text it sits beside. It is an image with a
+  name, not decoration: `role="img"` plus a localized label
+  (`chats.verified.label`, "Official account" / "Cuenta oficial"), and the
+  glyph is `aria-hidden` so a screen reader never announces it twice.
+- **`config.verified_badge`** `->(messager) { markup }` — swap the glyph for
+  your design system's own, vary it per messager, or return nil for no badge.
+  The default (nil) renders the gem's rosette.
+- **`--chats-verified`** (`#0284c7`) — the badge colour, a CSS custom
+  property like the rest of the gem's theming, inherited through
+  `currentColor`. Not the familiar `#1d9bf0`: the badge is a meaningful
+  graphic, so WCAG 1.4.11 asks 3:1 of it, and `#1d9bf0` is 3.00:1 on
+  `--chats-bg` but 2.73:1 on `--chats-surface` — the inbox row's HOVER
+  background, so it failed exactly while somebody was pointing at it.
+  `#0284c7` clears the bar on both grounds and on a dark one, so a host
+  inverting the palette inherits a badge that still passes.
+  `test/verified_badge_contrast_test.rb` computes it rather than trusting a
+  swatch.
+- **`chats_verified_badge(messager)`** — the view helper behind all three
+  surfaces, available in host views too. Nil for everyone who hasn't
+  declared `verified: true`, so it is safe to drop next to any name
+  unconditionally.
+- **`Chats::Conversation#counterpart_for(viewer)`** — the other messager in a
+  direct thread (nil for a group, and for a thread whose other seat left).
+  The title, the avatar and the badge on an inbox row now resolve the
+  counterpart through this one method, memoized per viewer, so a row that
+  cost one query in 0.2.0 still costs one.
+
+### Changed
+- The bundled inbox row wraps its title in `.chats-row__name`, and the thread
+  header wraps its name in `.chats-thread__name`, so a long name still
+  ellipsizes while the badge beside it stays visible. If you ejected these
+  views with `rails generate chats:views`, your copies are untouched and keep
+  working; re-run the generator only if you want the badge.
+
 ## [0.2.0] - 2026-09-16
 
 The release that makes `chats` a foundation other products can be built on:

data/README.md

@@ -97,7 +97,7 @@ Five concepts, namespaced and polymorphic from day one (no hard `User` coupling
 - **`Chats::Participant`** — a messager's seat in a conversation. Holds role, read horizon, mute, soft-leave, and notification bookkeeping.
 - **`Chats::Message`** — `text` (human) or `system` (posted by your app). Soft-deletes to a tombstone. Attachments via ActiveStorage.
 - **`Chats::Reaction`** — one row per (message, reactor, emoji); tap-to-toggle, race-safe.
-- **Any model with `acts_as_messager`** — users, organizations, support desks, bots: participants and senders are polymorphic. A messager that is not a person declares it (`notifications: false, blockable: false, inbox: :grouped`) and the gem stops treating it like one. See [`support_desk`](https://github.com/rameerez/support_desk) for the worked example.
+- **Any model with `acts_as_messager`** — users, organizations, support desks, bots: participants and senders are polymorphic. A messager that is not a person declares it (`notifications: false, blockable: false, inbox: :grouped`) and the gem stops treating it like one; an official one (`verified: true`) gets the badge everywhere its name appears. See [`support_desk`](https://github.com/rameerez/support_desk) for the worked example.
 
 Two deliberate design decisions worth knowing:
 
@@ -269,6 +269,53 @@ end
 
 That's the whole point of the option: **your notifiers and views stop asking `is_a?(User)`**. The predicates are on the class (`SupportDesk.chat_notifications?`, `.chat_blockable?`, `.chat_inbox_mode`) and duck-typed everywhere the gem reads them, so an ordinary `acts_as_messager` model behaves exactly as it always did.
 
+## ✅ Official accounts: the verified badge
+
+A support desk, an organization, a shop or a brand is an **official** counterpart, and the person talking to it should see that at a glance — the blue tick everyone already reads. Say it once, on the model, next to the other `acts_as_messager` options:
+
+```ruby
+class SupportDesk < ApplicationRecord
+  acts_as_messager verified: true
+end
+```
+
+Every bundled view that shows a messager's name now marks it: the inbox row, the stacked inbox row, and the thread header. The mark is an image with a name, not decoration — `role="img"` plus a localized label (`chats.verified.label`: "Official account" / "Cuenta oficial"), with the glyph itself `aria-hidden` so nothing is announced twice.
+
+`verified:` is **independent of everything else**. A desk is usually headless *and* official; a shop is usually official and completely ordinary otherwise. Combine what you need:
+
+```ruby
+acts_as_messager verified: true                                   # official, notifiable, blockable
+acts_as_messager notifications: false, inbox: :grouped, verified: true  # an official desk
+```
+
+It is the one boolean option that **refuses to coerce**, and that is deliberate — please don't "fix" it into a `!!` to match its neighbours. `notifications:` and `blockable:` coerce, so `notifications: "false"` quietly means `true`; on those two the damage is a stray notification. Here the same slip would hand an account the mark that tells people it is really us, and the strings that reach a model declaration come from exactly the places that produce `"false"`: an ENV var, a YAML round-trip, a settings row. So `verified: "false"` raises `Chats::ConfigurationError` at boot, where somebody is looking, rather than shipping a verified impostor nobody notices.
+
+Read it anywhere you render your own screens — duck-typed, never a class check:
+
+```ruby
+SupportDesk.chat_verified?       # the class predicate
+Chats.verified?(messager)        # false for a plain model, a nil, a non-messager
+chats_verified_badge(messager)   # the view helper: markup, or nil for everyone else
+```
+
+**Change the colour** with one CSS variable (the badge inherits it through `currentColor`):
+
+```css
+:root { --chats-verified: #0284c7; }
+```
+
+The default is `#0284c7` rather than the more familiar `#1d9bf0`. The badge is a meaningful graphic, so it owes 3:1 against what it sits on (WCAG 1.4.11), and `#1d9bf0` is 3.00:1 on the page but **2.73:1 on `--chats-surface`** — the inbox row's hover background, so it failed exactly while someone was pointing at it. `#0284c7` clears the bar on both (4.10 and 3.72) and on a dark ground too (4.33 on `#111827`), so inverting the palette doesn't leave you with a badge you have to remember to fix. If you override it, `test/verified_badge_contrast_test.rb` shows the arithmetic worth repeating.
+
+**Change the glyph** — to your design system's icon, a per-messager mark, or nothing — with a callable that gets the messager and returns html_safe markup (or `nil` for no badge):
+
+```ruby
+config.verified_badge = lambda do |messager|
+  ApplicationController.helpers.image_tag("official.svg", class: "badge", alt: "Official account")
+end
+```
+
+Or eject `app/views/chats/shared/_verified_badge.html.erb` with `rails generate chats:views` and rewrite it.
+
 ## 🗂️ Grouped inbox rows
 
 With `inbox: :grouped`, every direct conversation a viewer has with that messager folds into a single inbox row — a stack:
@@ -321,6 +368,10 @@ message.authored_by?(lucia)
 
 The bundled bubble renders a signature line ("— Lucía G.") via `Chats.display_name_for`; `config.message_signature = ->(message) { … }` rewrites it. Ordinary messages have no author and render exactly as before.
 
+An author must be persisted, but needs neither `acts_as_messager` nor a conversation
+seat. The host authorizes who may send on behalf of a shared identity; the HTTP
+message controller never accepts an author from request parameters.
+
 Existing installs get the columns with one command:
 
 ```bash
@@ -368,6 +419,7 @@ The bundled UI is intentionally framework-free (semantic `chats-*` classes + one
 :root {
   --chats-accent: #facc15;           /* own bubbles, send button, badges */
   --chats-accent-contrast: #111827;
+  --chats-verified: #0284c7;         /* the "official account" badge */
 }
 ```
 
@@ -409,7 +461,7 @@ Chats.configure do |config|
   config.max_group_size = 32
   config.max_attachment_size = 10.megabytes
   config.max_attachments_per_message = 4
-  config.send_rate_limit = { to: 60, within: 1.minute }  # Rails 8 rate_limit; nil disables
+  config.send_rate_limit = { to: 60, within: 1.minute }  # shared sender budget; nil disables
   config.encrypt_messages = false           # ActiveRecord Encryption on bodies
 
   # Policies (on top of — never instead of — block enforcement)
@@ -429,6 +481,7 @@ Chats.configure do |config|
   config.messager_avatar = ->(messager) { messager.avatar }  # URL/attachment/variant or nil
   config.messager_url = ->(messager) { nil }                 # nil ⇒ names render as plain text
   config.message_signature = nil                             # ->(message) { } for signed bubbles
+  config.verified_badge = nil                                # ->(messager) { markup } for verified: true
 end
 ```
 
@@ -445,10 +498,12 @@ alice.chats                                   # inbox relation, newest first
 alice.unread_chats_count                      # conversations with unread messages
 alice.message!(bob, "hi", author: lucia)      # written by lucia, sent from alice's seat
 Chats::Inbox.for(alice)                       # [Conversation | InboxGroup] + #unread_count
+Chats.verified?(desk)                         # official account? (acts_as_messager verified: true)
 
 # Conversations
 conversation.participant?(user)               # active membership
 conversation.other_participants(user)
+conversation.counterpart_for(viewer)          # the other messager (nil for groups)
 conversation.title_for(viewer)                # counterpart name / group title
 conversation.subject_label                    # "Madrid → Barcelona"
 conversation.unread_count_for(user)

data/app/assets/stylesheets/chats.css

@@ -11,6 +11,7 @@
  *   :root {
  *     --chats-accent: #facc15;          /\* brand color: own bubbles, send button *\/
  *     --chats-accent-contrast: #111827; /\* text on top of the accent *\/
+ *     --chats-verified: #0284c7;        /\* the "official account" badge *\/
  *   }
  *
  * Want a completely different look? `rails g chats:views` ejects the
@@ -26,6 +27,7 @@
   --chats-border: rgba(0, 0, 0, 0.08);
   --chats-text: #111827;
   --chats-text-muted: #6b7280;
+  --chats-verified: #0284c7;
   --chats-bubble-bg: #f3f4f6;
   --chats-bubble-text: #111827;
   --chats-radius: 1.1rem;
@@ -79,6 +81,12 @@
   justify-content: space-between;
   gap: 0.75rem;
 }
+.chats-row__name {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  min-width: 0;
+}
 .chats-row__title {
   font-weight: 650;
   white-space: nowrap;
@@ -147,6 +155,34 @@
   user-select: none;
 }
 
+/* --- Verified messagers ------------------------------------------------------
+ *
+ * The "official account" mark (`acts_as_messager verified: true`). It sizes
+ * itself from the text it sits next to, so it reads right in an inbox row and
+ * in the thread header without either one hard-coding a pixel value. Recolour
+ * it with --chats-verified; replace the glyph with config.verified_badge.
+ *
+ * On #0284c7 rather than the more familiar #1d9bf0: the badge is a meaningful
+ * graphic, so WCAG 1.4.11 asks for 3:1 against what it sits on, and #1d9bf0
+ * is 3.00:1 on --chats-bg but only 2.73:1 on --chats-surface — which is the
+ * row hover background, so the mark failed exactly while someone was pointing
+ * at it. #0284c7 clears 3:1 on both (4.10 and 3.72) and on a dark ground too
+ * (4.33 on #111827), so a host that inverts the palette inherits a badge that
+ * still passes instead of one it has to remember to fix. Pinned by
+ * test/verified_badge_contrast_test.rb.
+ */
+.chats-verified {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  color: var(--chats-verified);
+  line-height: 0;
+}
+.chats-verified__glyph {
+  width: 1em;
+  height: 1em;
+}
+
 /* --- Thread -------------------------------------------------------------------- */
 
 .chats-thread {
@@ -179,6 +215,12 @@
   font-size: 1rem;
   font-weight: 750;
   margin: 0;
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  min-width: 0;
+}
+.chats-thread__name {
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;

data/app/controllers/chats/conversations_controller.rb

@@ -189,10 +189,7 @@ module Chats
     def chats_counterpart
       return @chats_counterpart if defined?(@chats_counterpart)
 
-      @chats_counterpart =
-        if @conversation&.direct?
-          @conversation.other_participants(chats_current_messager).includes(:messager).first&.messager
-        end
+      @chats_counterpart = @conversation&.counterpart_for(chats_current_messager)
     end
   end
 end

data/app/controllers/chats/messages_controller.rb

@@ -12,19 +12,7 @@ module Chats
     # opened the composer" race in one place.
     before_action :refuse_when_locked!, only: %i[update destroy]
 
-    # Per-sender send throttle via Rails 8's built-in controller rate
-    # limiting (https://api.rubyonrails.org/classes/ActionController/RateLimiting.html).
-    # Feature-detected so the gem still loads on Rails 7.1 (where this is
-    # simply not enforced). Keyed by messager, not IP — one abusive account
-    # behind a corporate NAT must not silence the rest.
-    if respond_to?(:rate_limit) && Chats.config.send_rate_limit
-      rate_limit(
-        **Chats.config.send_rate_limit,
-        only: :create,
-        by: -> { send(Chats.config.current_messager_method)&.to_gid&.to_s || request.remote_ip },
-        with: -> { head :too_many_requests }
-      )
-    end
+    include Chats::SendRateLimited
 
     # A single bubble, re-rendered. Exists for one delightful reason: it's
     # the "cancel edit" target — replacing the inline edit form back with the

data/app/helpers/chats/engine_helper.rb

@@ -128,8 +128,7 @@ module Chats
     # initials disc from the group name.
     def chats_conversation_avatar(conversation, viewer)
       if conversation.direct?
-        other = conversation.other_participants(viewer).first
-        chats_messager_avatar(other&.messager)
+        chats_messager_avatar(conversation.counterpart_for(viewer))
       else
         initials = conversation.title_for(viewer).split.first(2).map { |word| word[0] }.join.upcase
         tag.span(initials.presence || "👥", class: "chats-avatar chats-avatar--initials chats-avatar--group",
@@ -195,6 +194,24 @@ module Chats
       url.present? ? link_to(name, url, class: css_class) : tag.span(name, class: css_class)
     end
 
+    # The "official account" mark for a messager declared `acts_as_messager
+    # verified: true`, and NIL for everyone else — so any view, bundled or
+    # host, can drop it next to a name unconditionally:
+    #
+    #   <%= chats_messager_name(author) %><%= chats_verified_badge(author) %>
+    #
+    # `config.verified_badge` swaps the glyph for the host's own design
+    # system; the default renders `chats/shared/_verified_badge`, whose
+    # colour is the `--chats-verified` CSS variable.
+    def chats_verified_badge(messager)
+      return unless Chats.verified?(messager)
+
+      custom = Chats.config.verified_badge
+      return custom.call(messager) if custom
+
+      render(partial: "chats/shared/verified_badge", locals: { messager: messager })
+    end
+
     # The signature line under a signed message ("— Lucía G."), or nil.
     def chats_message_signature(message)
       Chats.message_signature_for(message)

data/app/views/chats/conversations/_conversation_row.html.erb

@@ -7,7 +7,13 @@
 
     <span class="chats-row__body">
       <span class="chats-row__top">
-        <span class="chats-row__title"><%= conversation.title_for(viewer) %></span>
+        <%# The badge sits OUTSIDE the ellipsizing title so a long name
+            truncates without ever eating the mark. Nil for an ordinary
+            counterpart and for groups, so the row is unchanged. %>
+        <span class="chats-row__name">
+          <span class="chats-row__title"><%= conversation.title_for(viewer) %></span>
+          <%= chats_verified_badge(conversation.counterpart_for(viewer)) %>
+        </span>
         <time class="chats-row__time" datetime="<%= conversation.last_message_at&.iso8601 %>">
           <%= chats_timestamp(conversation.last_message_at) %>
         </time>

data/app/views/chats/conversations/_group.html.erb

@@ -13,7 +13,10 @@
 
     <span class="chats-row__body">
       <span class="chats-row__top">
-        <span class="chats-row__title"><%= group.title_for(viewer) %></span>
+        <span class="chats-row__name">
+          <span class="chats-row__title"><%= group.title_for(viewer) %></span>
+          <%= chats_verified_badge(group.messager) %>
+        </span>
         <time class="chats-row__time" datetime="<%= group.last_message_at&.iso8601 %>">
           <%= chats_timestamp(group.last_message_at) %>
         </time>

data/app/views/chats/conversations/show.html.erb

@@ -44,11 +44,15 @@
     <% end %>
 
     <div class="chats-thread__identity">
+      <%# Both arms wrap the name in .chats-thread__name: the <h1> is a flex
+          row (the badge is its second child), and only a real element can
+          carry the ellipsis. %>
       <h1 class="chats-thread__title">
         <% if chats_counterpart %>
-          <%= chats_messager_name(chats_counterpart) %>
+          <%= chats_messager_name(chats_counterpart, css_class: "chats-thread__name") %>
+          <%= chats_verified_badge(chats_counterpart) %>
         <% else %>
-          <%= @conversation.title_for(chats_current_messager) %>
+          <span class="chats-thread__name"><%= @conversation.title_for(chats_current_messager) %></span>
         <% end %>
       </h1>
       <% if @conversation.subject_label %>

data/app/views/chats/shared/_verified_badge.html.erb

@@ -0,0 +1,32 @@
+<%# The "official account" mark. Rendered next to a verified messager's name
+    (`acts_as_messager verified: true`) in every bundled view that shows one:
+    the inbox row, the stacked row and the thread header.
+
+    It is an IMAGE with a name, not decoration: the wrapper carries
+    role="img" plus the localized label, so a screen reader announces
+    "Cuenta oficial" / "Official account" where a sighted person sees the
+    badge, and the glyph itself is aria-hidden so it is never read twice.
+
+    The glyph is heroicons `check-badge` (24/solid): a scalloped rosette
+    with a TICK knocked out of it, which is the mark people already read as
+    "verified". It is deliberately not a plain star — a star says "favourite"
+    or "rated", and at 14px a solid star and a solid rosette are the same
+    blob, so the tick is the whole point. `fill-rule: evenodd` is what knocks
+    the tick out; without it the rosette fills solid and the mark is a blob.
+
+    Colour comes from the --chats-verified CSS variable (see chats.css) via
+    `fill: currentColor` — override that variable, or swap this whole partial
+    with `config.verified_badge`. %>
+<span class="chats-verified"
+      role="img"
+      title="<%= t("chats.verified.label") %>"
+      aria-label="<%= t("chats.verified.label") %>">
+  <svg xmlns="http://www.w3.org/2000/svg"
+       viewBox="0 0 24 24"
+       fill="currentColor"
+       class="chats-verified__glyph"
+       aria-hidden="true"
+       focusable="false">
+    <path fill-rule="evenodd" clip-rule="evenodd" d="M8.603 3.799A4.49 4.49 0 0 1 12 2.25c1.357 0 2.573.6 3.397 1.549a4.49 4.49 0 0 1 3.498 1.307 4.491 4.491 0 0 1 1.307 3.497A4.49 4.49 0 0 1 21.75 12a4.49 4.49 0 0 1-1.549 3.397 4.491 4.491 0 0 1-1.307 3.497 4.491 4.491 0 0 1-3.497 1.307A4.49 4.49 0 0 1 12 21.75a4.49 4.49 0 0 1-3.397-1.549 4.49 4.49 0 0 1-3.498-1.306 4.491 4.491 0 0 1-1.307-3.498A4.49 4.49 0 0 1 2.25 12c0-1.357.6-2.573 1.549-3.397a4.49 4.49 0 0 1 1.307-3.497 4.49 4.49 0 0 1 3.497-1.307Zm7.007 6.387a.75.75 0 1 0-1.22-.872l-3.236 4.53L9.53 12.22a.75.75 0 0 0-1.06 1.06l2.25 2.25a.75.75 0 0 0 1.14-.094l3.75-5.25Z" />
+  </svg>
+</span>

data/config/locales/en.yml

@@ -30,6 +30,8 @@ en:
       see_all: "See all"
     conversation:
       empty_title: "Conversation"
+    verified:
+      label: "Official account"
     message:
       deleted: "Message deleted"
       edited: "edited"

data/config/locales/es.yml

@@ -30,6 +30,8 @@ es:
       see_all: "Ver todas"
     conversation:
       empty_title: "Conversación"
+    verified:
+      label: "Cuenta oficial"
     message:
       deleted: "Mensaje eliminado"
       edited: "editado"

data/lib/chats/configuration.rb

@@ -153,6 +153,17 @@ module Chats
     # "— Author Name".
     attr_reader :message_signature
 
+    # ->(messager) { markup } — the badge shown next to an OFFICIAL
+    # account's name (`acts_as_messager verified: true`). nil (the default)
+    # renders the gem's own rosette, `chats/shared/_verified_badge`, coloured
+    # by the `--chats-verified` CSS variable.
+    #
+    # Return an html_safe value (anything `render`, `tag` or `image_tag`
+    # gives you) — a bare String is escaped, exactly as it would be anywhere
+    # else in a Rails view. Returning nil renders nothing, so a host can
+    # suppress the badge on some messagers without touching the models.
+    attr_reader :verified_badge
+
     def initialize
       @messager_class = "User"
       @parent_controller = "::ApplicationController"
@@ -187,6 +198,7 @@ module Chats
       @notifier = ->(_event, **_payload) {}
       @messager_url = ->(_messager) { nil }
       @message_signature = nil
+      @verified_badge = nil
 
       @messager_display_name = lambda do |messager|
         messager.try(:display_name) || messager.try(:name) ||
@@ -296,6 +308,10 @@ module Chats
       @message_signature = value.nil? ? nil : ensure_callable(value, "message_signature")
     end
 
+    def verified_badge=(value)
+      @verified_badge = value.nil? ? nil : ensure_callable(value, "verified_badge")
+    end
+
     def messager_display_name=(value)
       @messager_display_name = ensure_callable(value, "messager_display_name")
     end

data/lib/chats/engine.rb

@@ -30,7 +30,7 @@ module Chats
     CHATS_LIB = File.expand_path("chats", LIB_ROOT)
 
     ZEITWERK_IGNORED = %w[
-      version.rb errors.rb configuration.rb engine.rb macros.rb subscribers.rb
+      version.rb errors.rb configuration.rb engine.rb macros.rb subscribers.rb send_rate_limited.rb
     ].freeze
 
     initializer "chats.autoload", before: :set_autoload_paths do

data/lib/chats/inbox.rb

@@ -151,10 +151,13 @@ module Chats
       else
         stacked = Chats::Conversation.direct.where(id: stacked_seats)
         @ungrouped_relation = base_relation.where.not(id: stacked).limit(limit)
-        # Ordered by recency and limited like the other leg, which also makes
-        # the FIRST conversation of each counterpart that counterpart's
-        # freshest — that's the one the stacked row previews.
-        @stacked = apply_search(base_relation.direct.where(id: stacked_seats).limit(limit))
+        recent = base_relation.direct.where(id: stacked_seats).except(:includes).select(:id).limit(limit)
+        # Preserve the recent search window, plus the freshest conversation
+        # of each counterpart. A busy stack cannot consume another stack's
+        # row; at most twice the row limit is materialized.
+        candidates = base_relation.where(id: limited_ids(recent))
+                                  .or(base_relation.where(id: limited_ids(stack_representatives)))
+        @stacked = apply_search(candidates)
       end
 
       @ungrouped = apply_search(@ungrouped_relation)
@@ -163,6 +166,29 @@ module Chats
       @flat = @stacked.empty? && query.nil? ? @ungrouped_relation : @ungrouped + @stacked
     end
 
+    # MySQL rejects LIMIT directly in an IN subquery. A derived table keeps
+    # the bounded selection in SQL and works on all three supported adapters.
+    def limited_ids(relation)
+      Chats::Conversation.from(relation, :limited_conversations).select(:id)
+    end
+
+    # ROW_NUMBER works on every supported adapter (PostgreSQL, SQLite and
+    # MySQL 8). Ranking in SQL avoids loading an entire busy desk's history.
+    def stack_representatives
+      activity = "COALESCE(chats_conversations.last_message_at, chats_conversations.created_at)"
+      ranking = "ROW_NUMBER() OVER (PARTITION BY stack_seats.messager_type, stack_seats.messager_id " \
+                "ORDER BY #{activity} DESC, chats_conversations.id DESC) AS stack_rank"
+      ranked = base_relation.direct.except(:includes, :order)
+                            .joins("INNER JOIN chats_participants stack_seats " \
+                                   "ON stack_seats.conversation_id = chats_conversations.id")
+                            .where(stack_seats: { messager_type: grouped_types })
+                            .where.not(stack_seats: { messager_type: viewer.class.polymorphic_name,
+                                                      messager_id: viewer.id })
+                            .select("chats_conversations.id, #{activity} AS activity_at", ranking)
+      Chats::Conversation.from(ranked, :ranked_stacks).where("stack_rank = 1")
+                         .order(Arel.sql("activity_at DESC, id DESC")).limit(limit).select(:id)
+    end
+
     # Only the direct threads shared with one counterpart. Direct only, by
     # design: a group that happens to include the desk is not part of the
     # desk's stack.

data/lib/chats/macros.rb

@@ -29,18 +29,27 @@ module Chats
     #                          stacks into ONE inbox row (see Chats::Inbox).
     #   group_path: ->(viewer) { }  where that stacked row links to; defaults
     #                          to the filtered inbox (`?with=<sgid>`).
+    #   verified: true         this messager is an OFFICIAL account — a support
+    #                          desk, an organization, a brand. The bundled views
+    #                          mark its name with the rosette everyone already
+    #                          reads as "verified". Strictly true/false: a badge
+    #                          is a trust claim, so a stray "false" string must
+    #                          raise rather than quietly verify.
     #
     #   class Desk < ApplicationRecord
-    #     acts_as_messager notifications: false, blockable: false, inbox: :grouped
+    #     acts_as_messager notifications: false, blockable: false, inbox: :grouped,
+    #                      verified: true
     #   end
-    def acts_as_messager(notifications: true, blockable: true, inbox: :default, group_path: nil)
+    def acts_as_messager(notifications: true, blockable: true, inbox: :default, group_path: nil,
+                         verified: false)
       include Chats::Messager
 
       self.chat_options = Chats::Messager.normalize_options(
         notifications: notifications,
         blockable: blockable,
         inbox: inbox,
-        group_path: group_path
+        group_path: group_path,
+        verified: verified
       )
     end
 

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

@@ -22,14 +22,15 @@ module Chats
       notifications: true,
       blockable: true,
       inbox: :default,
-      group_path: nil
+      group_path: nil,
+      verified: false
     }.freeze
 
     INBOX_MODES = %i[default grouped].freeze
 
     # Validate + freeze the macro's options, failing at BOOT with a plain
     # English message rather than at 3am with a NoMethodError.
-    def self.normalize_options(notifications:, blockable:, inbox:, group_path:)
+    def self.normalize_options(notifications:, blockable:, inbox:, group_path:, verified: false)
       inbox = inbox.to_sym
       unless INBOX_MODES.include?(inbox)
         raise Chats::ConfigurationError,
@@ -41,11 +42,21 @@ module Chats
               "acts_as_messager group_path: must respond to #call (a proc/lambda), got #{group_path.inspect}"
       end
 
+      # Deliberately STRICTER than its boolean neighbours, which coerce with
+      # `!!`. "Official account" is a trust claim shown to everyone who talks
+      # to this messager, so `verified: "false"` (an ENV var, a YAML
+      # round-trip) has to fail at boot rather than quietly verify it.
+      unless [true, false].include?(verified)
+        raise Chats::ConfigurationError,
+              "acts_as_messager verified: must be true or false, got #{verified.inspect}"
+      end
+
       {
         notifications: !!notifications,
         blockable: !!blockable,
         inbox: inbox,
-        group_path: group_path
+        group_path: group_path,
+        verified: verified
       }.freeze
     end
 
@@ -76,6 +87,13 @@ module Chats
       def chat_group_path
         chat_options[:group_path]
       end
+
+      # True when declared with `acts_as_messager verified: true` — an
+      # OFFICIAL account (a support desk, an organization, a brand). The
+      # bundled views badge its name wherever they show it.
+      def chat_verified?
+        chat_options[:verified]
+      end
     end
 
     included do
@@ -138,11 +156,6 @@ module Chats
     #
     #   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

data/lib/chats/models/conversation.rb

@@ -114,6 +114,8 @@ module Chats
     # mechanism. https://api.rubyonrails.org/classes/ActiveRecord/Relation.html#method-i-create_or_find_by
     validate :groups_must_be_enabled, if: :group?
 
+    after_create_commit -> { Chats.notify(:conversation_created, conversation: self) }
+
     # --- Finding & creating ---------------------------------------------------
 
     class << self
@@ -133,21 +135,17 @@ module Chats
         raise Chats::BlockedError, "messagers are blocked" if Chats.blocked_between?(a, b)
         raise Chats::NotAllowedError, "policy forbids messaging" unless Chats.can_message?(a, b)
 
-        conversation = create_or_find_by!(direct_key: direct_key_for([a, b], subject: about)) do |c|
-          c.kind = "direct"
-          c.subject = about
+        transaction do
+          conversation = create_or_find_by!(direct_key: direct_key_for([a, b], subject: about)) do |c|
+            c.kind = "direct"
+            c.subject = about
+          end
+          # Keep the roster in the creation transaction: the after-commit
+          # event must describe a complete conversation, including under an
+          # outer host transaction or a failed participant insertion.
+          [a, b].each { |messager| conversation.add_participant!(messager) }
+          conversation
         end
-
-        # `create_or_find_by!` may have FOUND a conversation created a moment
-        # ago by the other side — participants are ensured idempotently
-        # either way (their own unique index makes this race-safe too).
-        # `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
 
       # Create a group conversation. +others+ excludes the creator (who joins
@@ -163,17 +161,12 @@ module Chats
         others = Array(others) - [creator]
         raise ArgumentError, "a group needs at least 2 other participants" if others.size < 2
 
-        conversation = transaction do
+        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).
@@ -222,13 +215,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)

data/lib/chats/models/message.rb

@@ -96,7 +96,7 @@ module Chats
     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 :author_must_be_persisted
     validate :files_must_be_allowed
 
     after_create :register_on_conversation
@@ -312,13 +312,13 @@ 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)
+    # Authorship is a signature, not a conversation seat. A host may keep
+    # staff in a separate model without giving them messaging capabilities.
+    # Never implicitly create that identity while sending a message.
+    def author_must_be_persisted
+      return if author.nil? || author.persisted?
 
-      errors.add(:author, :not_a_messager)
+      errors.add(:author, :invalid)
     end
 
     # The subject owns the conversation's openness (Chats::ChatSubject#

data/lib/chats/models/participant.rb

@@ -43,6 +43,8 @@ module Chats
     # concurrent joins race-safe. Same rationale as Conversation#direct_key.
     validate :group_must_have_room, on: :create
 
+    after_update_commit :notify_departure, if: -> { saved_change_to_left_at? && left? }
+
     def owner? = role == "owner"
     def left? = left_at.present?
     def active? = left_at.nil?
@@ -104,11 +106,17 @@ module Chats
     def unmute! = update!(muted_at: nil)
 
     def leave!
+      return self if left?
+
       update!(left_at: Time.current)
-      Chats.notify(:participant_left, participant: self)
       self
     end
 
+    def notify_departure
+      Chats.notify(:participant_left, participant: self)
+    end
+    private :notify_departure
+
     # 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

data/lib/chats/send_rate_limited.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Chats
+  # Share one sender budget across chat and product-specific HTTP composers.
+  # The host owns the cache store. Using its atomic increment also works on
+  # Rails 7 and avoids depending on Rails' private controller limiter API.
+  module SendRateLimited
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :enforce_chat_send_rate_limit, only: :create
+    end
+
+    private
+
+    def chat_rate_limit_messager
+      send(Chats.config.current_messager_method)
+    end
+
+    def enforce_chat_send_rate_limit
+      limit = Chats.config.send_rate_limit
+      return unless limit
+
+      sender = chat_rate_limit_messager&.to_gid&.to_s || request.remote_ip
+      count = self.class.cache_store.increment("rate-limit:chats/messages:#{sender}", 1,
+                                               expires_in: limit.fetch(:within))
+      head :too_many_requests if count && count > limit.fetch(:to)
+    end
+  end
+end

data/lib/chats/version.rb

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

data/lib/chats.rb

@@ -7,6 +7,7 @@ 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)
@@ -219,6 +220,14 @@ module Chats
       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

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

@@ -19,8 +19,10 @@ Chats.configure do |config|
   #   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")
+  #                      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
@@ -200,6 +202,15 @@ Chats.configure do |config|
   # 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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: chats
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.2
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-09-16 00:00:00.000000000 Z
+date: 2026-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -151,6 +151,8 @@ files:
 - 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
+- chats-0.3.1.gem
 - config/importmap.rb
 - config/locales/en.yml
 - config/locales/es.yml
@@ -176,6 +178,7 @@ files:
 - lib/chats/models/message.rb
 - lib/chats/models/participant.rb
 - lib/chats/models/reaction.rb
+- lib/chats/send_rate_limited.rb
 - lib/chats/subscribers.rb
 - lib/chats/version.rb
 - lib/generators/chats/install_generator.rb