livechat 0.1.0

data/config/locales/livechat.ru.yml

@@ -0,0 +1,44 @@
+ru:
+  livechat:
+    launcher: "Напишите нам"
+    greeting: "Здравствуйте! Чем можем помочь?"
+    reply_time: "Обычно мы отвечаем в течение нескольких часов."
+    placeholder: "Напишите сообщение…"
+    send: "Отправить"
+    close: "Закрыть"
+    you: "Вы"
+    team: "Поддержка"
+    email_prompt: "Получите копию нашего ответа по электронной почте:"
+    email_placeholder: "you@example.com"
+    email_save: "Сохранить"
+    email_saved: "Мы также ответим по электронной почте."
+    event_resolved: "Диалог завершён"
+    event_reopened: "Диалог возобновлён"
+    error_send: "Не удалось отправить. Пожалуйста, попробуйте ещё раз."
+    error_rate_limited: "Слишком много сообщений. Подождите немного и попробуйте ещё раз."
+    unread_aria: "непрочитанные сообщения"
+    statuses:
+      open: "Открыт"
+      resolved: "Завершён"
+    events:
+      resolved: "%{agent} завершил(а) диалог"
+      reopened: "%{agent} возобновил(а) диалог"
+    dashboard:
+      title: "Чат"
+      empty: "Пока здесь пусто. Когда посетитель напишет, диалог появится на этой странице."
+      visitor: "Посетитель"
+      last_message: "Последнее сообщение"
+      updated: "Обновлено"
+      back: "Все диалоги"
+      resolve: "Завершить"
+      reopen: "Возобновить"
+      reply_placeholder: "Напишите ответ…"
+      send: "Отправить"
+      new_messages: "Новые сообщения — обновите"
+      newer: "Новее"
+      older: "Старше"
+    mail:
+      visitor_subject: "%{name} написал(а) вам в %{app}"
+      reply_subject: "%{name} ответил(а) вам в %{app}"
+      answer: "Ответить"
+      continue: "Продолжить диалог"

data/config/locales/livechat.th.yml

@@ -0,0 +1,44 @@
+th:
+  livechat:
+    launcher: "แชทกับเรา"
+    greeting: "สวัสดี! เราช่วยอะไรคุณได้บ้าง"
+    reply_time: "โดยปกติเราจะตอบกลับภายในไม่กี่ชั่วโมง"
+    placeholder: "เขียนข้อความ…"
+    send: "ส่ง"
+    close: "ปิด"
+    you: "คุณ"
+    team: "ฝ่ายสนับสนุน"
+    email_prompt: "รับสำเนาคำตอบของเราทางอีเมล:"
+    email_placeholder: "you@example.com"
+    email_save: "บันทึก"
+    email_saved: "เราจะตอบกลับทางอีเมลด้วย"
+    event_resolved: "การสนทนาได้รับการแก้ไขแล้ว"
+    event_reopened: "เปิดการสนทนาอีกครั้งแล้ว"
+    error_send: "ส่งไม่สำเร็จ โปรดลองอีกครั้ง"
+    error_rate_limited: "ข้อความมากเกินไป โปรดรอสักครู่แล้วลองอีกครั้ง"
+    unread_aria: "ข้อความที่ยังไม่ได้อ่าน"
+    statuses:
+      open: "เปิดอยู่"
+      resolved: "แก้ไขแล้ว"
+    events:
+      resolved: "%{agent} แก้ไขการสนทนาแล้ว"
+      reopened: "%{agent} เปิดการสนทนาอีกครั้ง"
+    dashboard:
+      title: "แชท"
+      empty: "ยังไม่มีอะไรที่นี่ เมื่อผู้เยี่ยมชมส่งข้อความ การสนทนาจะปรากฏบนหน้านี้"
+      visitor: "ผู้เยี่ยมชม"
+      last_message: "ข้อความล่าสุด"
+      updated: "อัปเดตเมื่อ"
+      back: "การสนทนาทั้งหมด"
+      resolve: "แก้ไขเสร็จสิ้น"
+      reopen: "เปิดอีกครั้ง"
+      reply_placeholder: "เขียนคำตอบของคุณ…"
+      send: "ส่ง"
+      new_messages: "มีข้อความใหม่ — รีเฟรช"
+      newer: "ใหม่กว่า"
+      older: "เก่ากว่า"
+    mail:
+      visitor_subject: "%{name} เขียนถึงคุณบน %{app}"
+      reply_subject: "%{name} ตอบกลับคุณบน %{app}"
+      answer: "ตอบกลับ"
+      continue: "สนทนาต่อ"

data/config/locales/livechat.tr.yml

@@ -0,0 +1,44 @@
+tr:
+  livechat:
+    launcher: "Bizimle sohbet edin"
+    greeting: "Merhaba! Size nasıl yardımcı olabiliriz?"
+    reply_time: "Genellikle birkaç saat içinde yanıtlıyoruz."
+    placeholder: "Bir mesaj yazın…"
+    send: "Gönder"
+    close: "Kapat"
+    you: "Siz"
+    team: "Destek"
+    email_prompt: "Yanıtımızın bir kopyasını e-postayla alın:"
+    email_placeholder: "siz@ornek.com"
+    email_save: "Kaydet"
+    email_saved: "Ayrıca e-postayla da yanıtlayacağız."
+    event_resolved: "Görüşme çözüldü"
+    event_reopened: "Görüşme yeniden açıldı"
+    error_send: "Gönderilemedi. Lütfen tekrar deneyin."
+    error_rate_limited: "Çok fazla mesaj. Lütfen biraz bekleyip tekrar deneyin."
+    unread_aria: "okunmamış mesaj"
+    statuses:
+      open: "Açık"
+      resolved: "Çözüldü"
+    events:
+      resolved: "%{agent} görüşmeyi çözdü"
+      reopened: "%{agent} görüşmeyi yeniden açtı"
+    dashboard:
+      title: "Sohbet"
+      empty: "Henüz burada bir şey yok. Bir ziyaretçi yazdığında görüşme bu sayfada görünür."
+      visitor: "Ziyaretçi"
+      last_message: "Son mesaj"
+      updated: "Güncellendi"
+      back: "Tüm görüşmeler"
+      resolve: "Çöz"
+      reopen: "Yeniden aç"
+      reply_placeholder: "Yanıtınızı yazın…"
+      send: "Gönder"
+      new_messages: "Yeni mesajlar — yenileyin"
+      newer: "Daha yeni"
+      older: "Daha eski"
+    mail:
+      visitor_subject: "%{name}, %{app} üzerinden size yazdı"
+      reply_subject: "%{name}, %{app} üzerinden size yanıt verdi"
+      answer: "Yanıtla"
+      continue: "Görüşmeye devam et"

data/config/locales/livechat.uk.yml

@@ -0,0 +1,44 @@
+uk:
+  livechat:
+    launcher: "Напишіть нам"
+    greeting: "Вітаємо! Чим можемо допомогти?"
+    reply_time: "Зазвичай ми відповідаємо протягом кількох годин."
+    placeholder: "Напишіть повідомлення…"
+    send: "Надіслати"
+    close: "Закрити"
+    you: "Ви"
+    team: "Підтримка"
+    email_prompt: "Отримайте копію нашої відповіді електронною поштою:"
+    email_placeholder: "you@example.com"
+    email_save: "Зберегти"
+    email_saved: "Ми також відповімо електронною поштою."
+    event_resolved: "Розмову завершено"
+    event_reopened: "Розмову відновлено"
+    error_send: "Не вдалося надіслати. Будь ласка, спробуйте ще раз."
+    error_rate_limited: "Забагато повідомлень. Зачекайте трохи та спробуйте ще раз."
+    unread_aria: "непрочитані повідомлення"
+    statuses:
+      open: "Відкрита"
+      resolved: "Завершена"
+    events:
+      resolved: "%{agent} завершив(ла) розмову"
+      reopened: "%{agent} відновив(ла) розмову"
+    dashboard:
+      title: "Чат"
+      empty: "Поки що тут порожньо. Коли відвідувач напише, розмова з'явиться на цій сторінці."
+      visitor: "Відвідувач"
+      last_message: "Останнє повідомлення"
+      updated: "Оновлено"
+      back: "Усі розмови"
+      resolve: "Завершити"
+      reopen: "Відновити"
+      reply_placeholder: "Напишіть відповідь…"
+      send: "Надіслати"
+      new_messages: "Нові повідомлення — оновіть"
+      newer: "Новіші"
+      older: "Старіші"
+    mail:
+      visitor_subject: "%{name} написав(ла) вам у %{app}"
+      reply_subject: "%{name} відповів(ла) вам у %{app}"
+      answer: "Відповісти"
+      continue: "Продовжити розмову"

data/config/locales/livechat.ur.yml

@@ -0,0 +1,44 @@
+ur:
+  livechat:
+    launcher: "ہم سے چیٹ کریں"
+    greeting: "ہیلو! ہم آپ کی کیا مدد کر سکتے ہیں؟"
+    reply_time: "ہم عام طور پر چند گھنٹوں میں جواب دیتے ہیں۔"
+    placeholder: "پیغام لکھیں…"
+    send: "بھیجیں"
+    close: "بند کریں"
+    you: "آپ"
+    team: "سپورٹ"
+    email_prompt: "ہمارے جواب کی ایک نقل ای میل پر حاصل کریں:"
+    email_placeholder: "you@example.com"
+    email_save: "محفوظ کریں"
+    email_saved: "ہم ای میل پر بھی جواب دیں گے۔"
+    event_resolved: "گفتگو حل ہو گئی"
+    event_reopened: "گفتگو دوبارہ کھول دی گئی"
+    error_send: "بھیجا نہیں جا سکا۔ براہ کرم دوبارہ کوشش کریں۔"
+    error_rate_limited: "بہت زیادہ پیغامات۔ براہ کرم تھوڑا انتظار کریں اور دوبارہ کوشش کریں۔"
+    unread_aria: "غیر پڑھے گئے پیغامات"
+    statuses:
+      open: "کھلی"
+      resolved: "حل شدہ"
+    events:
+      resolved: "%{agent} نے گفتگو حل کر دی"
+      reopened: "%{agent} نے گفتگو دوبارہ کھول دی"
+    dashboard:
+      title: "چیٹ"
+      empty: "یہاں ابھی کچھ نہیں ہے۔ جب کوئی وزیٹر لکھے گا تو گفتگو اس صفحے پر نظر آئے گی۔"
+      visitor: "وزیٹر"
+      last_message: "آخری پیغام"
+      updated: "اپ ڈیٹ"
+      back: "تمام گفتگوئیں"
+      resolve: "حل کریں"
+      reopen: "دوبارہ کھولیں"
+      reply_placeholder: "اپنا جواب لکھیں…"
+      send: "بھیجیں"
+      new_messages: "نئے پیغامات — ریفریش کریں"
+      newer: "نئے"
+      older: "پرانے"
+    mail:
+      visitor_subject: "%{name} نے آپ کو %{app} پر لکھا"
+      reply_subject: "%{name} نے آپ کو %{app} پر جواب دیا"
+      answer: "جواب دیں"
+      continue: "گفتگو جاری رکھیں"

data/config/locales/livechat.vi.yml

@@ -0,0 +1,44 @@
+vi:
+  livechat:
+    launcher: "Trò chuyện với chúng tôi"
+    greeting: "Xin chào! Chúng tôi có thể giúp gì cho bạn?"
+    reply_time: "Chúng tôi thường trả lời trong vòng vài giờ."
+    placeholder: "Viết tin nhắn…"
+    send: "Gửi"
+    close: "Đóng"
+    you: "Bạn"
+    team: "Hỗ trợ"
+    email_prompt: "Nhận bản sao câu trả lời của chúng tôi qua email:"
+    email_placeholder: "you@example.com"
+    email_save: "Lưu"
+    email_saved: "Chúng tôi cũng sẽ trả lời qua email."
+    event_resolved: "Cuộc trò chuyện đã được giải quyết"
+    event_reopened: "Cuộc trò chuyện đã được mở lại"
+    error_send: "Không thể gửi. Vui lòng thử lại."
+    error_rate_limited: "Quá nhiều tin nhắn. Vui lòng đợi một lát rồi thử lại."
+    unread_aria: "tin nhắn chưa đọc"
+    statuses:
+      open: "Đang mở"
+      resolved: "Đã giải quyết"
+    events:
+      resolved: "%{agent} đã giải quyết cuộc trò chuyện"
+      reopened: "%{agent} đã mở lại cuộc trò chuyện"
+    dashboard:
+      title: "Trò chuyện"
+      empty: "Chưa có gì ở đây. Khi khách truy cập nhắn tin, cuộc trò chuyện sẽ xuất hiện trên trang này."
+      visitor: "Khách truy cập"
+      last_message: "Tin nhắn cuối"
+      updated: "Đã cập nhật"
+      back: "Tất cả cuộc trò chuyện"
+      resolve: "Giải quyết"
+      reopen: "Mở lại"
+      reply_placeholder: "Viết câu trả lời của bạn…"
+      send: "Gửi"
+      new_messages: "Tin nhắn mới — làm mới"
+      newer: "Mới hơn"
+      older: "Cũ hơn"
+    mail:
+      visitor_subject: "%{name} đã nhắn tin cho bạn trên %{app}"
+      reply_subject: "%{name} đã trả lời bạn trên %{app}"
+      answer: "Trả lời"
+      continue: "Tiếp tục cuộc trò chuyện"

data/config/locales/livechat.zh-CN.yml

@@ -0,0 +1,44 @@
+"zh-CN":
+  livechat:
+    launcher: "与我们聊天"
+    greeting: "您好！有什么可以帮您？"
+    reply_time: "我们通常会在几小时内回复。"
+    placeholder: "输入消息…"
+    send: "发送"
+    close: "关闭"
+    you: "您"
+    team: "客服"
+    email_prompt: "通过邮箱接收我们回复的副本："
+    email_placeholder: "you@example.com"
+    email_save: "保存"
+    email_saved: "我们也会通过邮件回复您。"
+    event_resolved: "对话已解决"
+    event_reopened: "对话已重新打开"
+    error_send: "发送失败，请重试。"
+    error_rate_limited: "消息过多，请稍等片刻再重试。"
+    unread_aria: "条未读消息"
+    statuses:
+      open: "进行中"
+      resolved: "已解决"
+    events:
+      resolved: "%{agent} 已解决该对话"
+      reopened: "%{agent} 重新打开了该对话"
+    dashboard:
+      title: "聊天"
+      empty: "这里还没有内容。当访客发来消息时，对话会显示在此页面。"
+      visitor: "访客"
+      last_message: "最后一条消息"
+      updated: "更新时间"
+      back: "所有对话"
+      resolve: "解决"
+      reopen: "重新打开"
+      reply_placeholder: "输入您的回复…"
+      send: "发送"
+      new_messages: "有新消息 — 请刷新"
+      newer: "较新"
+      older: "较旧"
+    mail:
+      visitor_subject: "%{name} 在 %{app} 上给您留言"
+      reply_subject: "%{name} 在 %{app} 上回复了您"
+      answer: "回复"
+      continue: "继续对话"

data/config/routes.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+Livechat::Engine.routes.draw do
+  get 'widget.js', to: 'widgets#show', as: :widget
+  get 'dashboard.js', to: 'widgets#dashboard', as: :dashboard_script
+
+  # The widget's API. Everything is scoped to the requesting visitor —
+  # signed-in id or guest cookie — never to an enumerable conversation id.
+  scope :widget, as: :widget do
+    get 'conversation', to: 'visitor#show'
+    post 'messages', to: 'visitor#create'
+    post 'email', to: 'visitor#email'
+    post 'read', to: 'visitor#read'
+  end
+
+  # The inbox. Flat, human URLs: the mount path IS the conversation list.
+  resources :conversations, path: '', only: %i[index show], constraints: { id: /\d+/ } do
+    member do
+      get :poll
+      post :resolve
+      post :reopen
+    end
+    resources :messages, only: :create
+  end
+
+  root to: 'conversations#index'
+end

data/lib/generators/livechat/install/install_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Livechat
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Installs livechat: config initializer, migration, and engine mount.'
+
+      def create_initializer
+        copy_file 'initializer.rb', 'config/initializers/livechat.rb'
+      end
+
+      def create_migration_file
+        migration_template 'create_livechat_tables.rb.tt',
+                           'db/migrate/create_livechat_tables.rb'
+      end
+
+      def mount_engine
+        route %(mount Livechat::Engine => "/livechat")
+      end
+
+      def post_install
+        say "\nlivechat installed. Run `rails db:migrate`, then add", :green
+        say '`<%= livechat_tag %>` before </body> in your layout.'
+        say 'Answer visitors at /livechat (development only until you set config.authorize_agent).'
+        say "Set config.mailer_from + config.agent_emails to hear about new messages by email.\n"
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/livechat/install/templates/create_livechat_tables.rb.tt

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class CreateLivechatTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :livechat_conversations do |t|
+      t.string :visitor_token
+      t.string :visitor_id
+      t.string :visitor_label
+      t.string :visitor_email
+      t.string :status, null: false, default: 'open'
+      t.string :last_message_preview
+      t.datetime :last_activity_at
+      t.string :page_url
+      t.string :locale
+
+      t.timestamps
+    end
+    add_index :livechat_conversations, :visitor_token
+    add_index :livechat_conversations, :visitor_id
+    add_index :livechat_conversations, :status
+    add_index :livechat_conversations, :last_activity_at
+
+    create_table :livechat_messages do |t|
+      t.references :conversation, null: false
+      t.string :author_type, null: false
+      t.string :agent_id
+      t.string :agent_label
+      t.text :body
+      t.string :event
+      t.datetime :read_at
+
+      t.timestamps
+    end
+    add_index :livechat_messages, %i[conversation_id id]
+  end
+end

data/lib/generators/livechat/install/templates/initializer.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+Livechat.configure do |config|
+  # Shown in the widget header and in notification emails. Defaults to your
+  # Rails application name.
+  # config.app_name = "My App"
+
+  # Who sees the widget and can write. Return false to hide and reject for
+  # this request. Defaults to everyone.
+  # config.enabled = ->(request) { true }
+
+  # Who can answer at the mount path. Defaults to development only — override
+  # before deploying.
+  # config.authorize_agent = ->(request) { request.env["warden"]&.user&.admin? }
+
+  # Resolve the current user (optional). Return an object responding to #id,
+  # or nil. Signed-in visitors keep one conversation across devices; guests
+  # are tracked with a cookie. The same user is the agent when replying.
+  # config.current_user = ->(request) { request.env["warden"]&.user }
+
+  # How visitors appear in the inbox.
+  # config.visitor_label = ->(user) { user.name.presence || user.email }
+
+  # How agents are attributed on their replies.
+  # config.agent_label = ->(user) { user.name.presence || user.email }
+
+  # What visitors see as the sender. Default: the agent_label unchanged.
+  # Return a first name, or a constant to keep the team anonymous.
+  # config.agent_display_name = ->(label) { label.split.first }
+
+  # Widget copy. nil = localized defaults.
+  # config.greeting = "Hi! How can we help?"
+  # config.reply_time_text = "We usually reply within a few hours."
+  # config.launcher_label = "Chat with us"
+
+  # Brand color (hex) for the launcher, header, bubbles and send button.
+  # Text flips black/white automatically for contrast. nil = built-in blue.
+  # config.accent_color = "#7c3aed"
+
+  # The floating bubble. Set false and open the widget from your own
+  # elements carrying data-livechat-open, or window.Livechat.open().
+  # config.show_launcher = true
+
+  # Email the team when a visitor writes and nobody has read it — one email
+  # per unread stretch, not one per message. Both settings are required.
+  # config.mailer_from = "chat@example.com"
+  # config.agent_emails = ["support@example.com"]
+  # config.agent_emails = -> { User.where(admin: true).pluck(:email) }
+
+  # Called with each saved Livechat::Message — notify Slack, push…
+  # config.on_visitor_message = ->(message) {}
+  # config.on_agent_message = ->(message) {}
+
+  # Per-IP throttle for the widget endpoints (Rails 7.2+; ignored on 7.1).
+  # config.rate_limit = { to: 30, within: 1.minute }
+
+  # Keep in sync with the `mount` in config/routes.rb.
+  # config.mount_path = "/livechat"
+end

data/lib/livechat/configuration.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Livechat
+  # Host-tunable settings. Everything has a safe default, so a fresh install
+  # works with zero configuration; the hooks below let an app decide who can
+  # chat, who answers, and how everyone is named.
+  class Configuration
+    # Shown in the widget header and in notification emails. nil resolves to
+    # the Rails application name.
+    attr_accessor :app_name
+
+    # Per-request gate for the widget and its endpoints. Return false to hide
+    # the widget and reject writes for this request.
+    attr_accessor :enabled
+
+    # Per-request gate for the inbox. Defaults to development only — override
+    # it before deploying, e.g. with an admin check. Independent of `enabled`,
+    # so your team can answer from production even where the widget is off.
+    attr_accessor :authorize_agent
+
+    # Resolve the current user (optional). Return an object responding to
+    # #id, or nil. Receives the request. Signed-in users keep one conversation
+    # across devices; guests are tracked with a cookie.
+    attr_accessor :current_user
+
+    # Turn a resolved user into the visitor name shown in the inbox.
+    attr_accessor :visitor_label
+
+    # Turn a resolved user into the attribution stored on an agent's message.
+    # Every reply carries this, so a thread with several teammates stays
+    # legible.
+    attr_accessor :agent_label
+
+    # What visitors see as the sender of an agent message. Receives the
+    # stored agent_label; return it unchanged (default), a first name, or a
+    # constant like "Support team" to keep agents anonymous.
+    attr_accessor :agent_display_name
+
+    # Widget copy. nil uses the localized defaults. reply_time_text is the
+    # honest line under the greeting — "We usually reply within a few hours."
+    attr_accessor :greeting, :reply_time_text, :launcher_label
+
+    # Brand color for the widget (launcher, header, visitor bubbles, send
+    # button) as a hex value, e.g. "#7c3aed". The widget picks black or white
+    # text automatically for contrast. nil keeps the built-in blue.
+    attr_accessor :accent_color
+
+    # The floating launcher bubble. Set false to open the widget only from
+    # your own elements carrying `data-livechat-open`.
+    attr_accessor :show_launcher
+
+    # Email addresses to notify when a visitor writes and nobody has read it —
+    # an array, or a callable returning one. nil disables the built-in email.
+    attr_accessor :agent_emails
+
+    # From-address for the built-in notification emails. Required for any
+    # email to be sent.
+    attr_accessor :mailer_from
+
+    # Called with each saved Livechat::Message — wire up Slack, Noticed,
+    # push… Runs inline after save; keep it fast or hand off to a job.
+    attr_accessor :on_visitor_message, :on_agent_message
+
+    # Per-IP throttle for the public endpoints, as keyword arguments for
+    # Rails' rate limiter (Rails 7.2+; ignored on 7.1). nil disables it.
+    attr_accessor :rate_limit
+
+    # Where the engine is mounted. The widget calls paths under it, so keep
+    # this in sync with the `mount` line in your routes.
+    attr_accessor :mount_path
+
+    def initialize
+      @app_name = nil
+      @enabled = ->(_request) { true }
+      @authorize_agent = ->(_request) { Rails.env.development? }
+      @current_user = ->(_request) {}
+      @visitor_label = ->(user) { user.try(:name).presence || user.try(:email).presence || user.to_s }
+      @agent_label = ->(user) { user.try(:name).presence || user.try(:email).presence || user.to_s }
+      @agent_display_name = ->(label) { label }
+      @greeting = nil
+      @reply_time_text = nil
+      @launcher_label = nil
+      @accent_color = nil
+      @show_launcher = true
+      @agent_emails = nil
+      @mailer_from = nil
+      @on_visitor_message = ->(_message) {}
+      @on_agent_message = ->(_message) {}
+      @rate_limit = { to: 30, within: 60 }
+      @mount_path = '/livechat'
+    end
+
+    def widget_endpoint = "#{mount_path.chomp('/')}/widget"
+
+    def agent_email_list
+      list = agent_emails
+      list = list.call if list.respond_to?(:call)
+      Array(list).compact_blank
+    end
+
+    def emails_enabled? = mailer_from.present?
+  end
+end

data/lib/livechat/dashboard.js

@@ -0,0 +1,58 @@
+/*
+ * livechat dashboard — the little JavaScript the inbox needs, served as a
+ * same-origin script so it works under strict CSPs (no inline handlers).
+ *
+ * On a conversation page it polls for new messages every few seconds. If the
+ * reply box is empty the page just reloads to show them; if the agent is
+ * mid-sentence it shows a "New messages" link instead — a reload must never
+ * eat a half-written reply. Cmd/Ctrl+Enter sends.
+ */
+(function () {
+  "use strict";
+
+  var POLL_MS = 5000;
+
+  function ready(fn) {
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", fn);
+    } else {
+      fn();
+    }
+  }
+
+  ready(function () {
+    var thread = document.getElementById("thread");
+    if (!thread) return;
+
+    thread.scrollTop = thread.scrollHeight;
+
+    var replyBox = document.querySelector(".reply textarea");
+    var banner = document.getElementById("new-messages");
+    var latest = parseInt(thread.getAttribute("data-latest"), 10) || 0;
+    var url = thread.getAttribute("data-poll-url");
+
+    if (replyBox) {
+      replyBox.addEventListener("keydown", function (event) {
+        if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) {
+          event.preventDefault();
+          replyBox.form.requestSubmit();
+        }
+      });
+    }
+
+    setInterval(function () {
+      if (document.hidden) return;
+      fetch(url, { headers: { Accept: "application/json" }, credentials: "same-origin" })
+        .then(function (response) { return response.ok ? response.json() : null; })
+        .then(function (data) {
+          if (!data || data.latest <= latest) return;
+          if (!replyBox || replyBox.value.trim() === "") {
+            window.location.reload();
+          } else if (banner) {
+            banner.hidden = false;
+          }
+        })
+        .catch(function () { /* transient network error — next tick retries */ });
+    }, POLL_MS);
+  });
+})();

data/lib/livechat/engine.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Livechat
+  class Engine < ::Rails::Engine
+    isolate_namespace Livechat
+
+    initializer 'livechat.helpers' do
+      ActiveSupport.on_load(:action_view) do
+        include Livechat::WidgetHelper
+      end
+    end
+  end
+end