livechat 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1f475396740f88ad5b62ea7f30889dd7e3b36699834f061d2a7d09cdf341b88a
+  data.tar.gz: cb58318b0d8ac30a316d59bca48e8eca3bbe63b697c0d744a2404820d9327344
+SHA512:
+  metadata.gz: e261a7ad6751071cafb5546af26cc27fe2191ff7425c8aa001d52dc7ce996d0a7176cce69aecae2b7f2e09dccf38b6536dabc1c71af06f790f80b536c45de37a
+  data.tar.gz: 443fe470e3d66f164a4f970ea4d0e3fdfdd41e42d98d5a05674ac9783e97f4c128ea5dfe97866ad034e4a71eb3cc412e4ec8cabfaf3449c7a727e903925328c2

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release: floating chat widget (guests + signed-in visitors, one
+  thread per visitor, email capture), team inbox with signed replies,
+  resolve/reopen with system messages, unread tracking on both sides,
+  polling transport (no Action Cable required), built-in notification
+  emails in both directions (one per unread stretch), `on_visitor_message` /
+  `on_agent_message` hooks, per-IP rate limiting, 26 languages, RTL, strict
+  CSP support.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 Yaroslav Shmarov
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,160 @@
+# livechat
+
+[![Gem Version](https://img.shields.io/gem/v/livechat)](https://rubygems.org/gems/livechat)
+[![CI](https://github.com/yshmarov/livechat/actions/workflows/ci.yml/badge.svg)](https://github.com/yshmarov/livechat/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](MIT-LICENSE)
+
+Open-source live chat for Rails. Self-hosted alternative to Crisp, Intercom
+and Chatwoot — as a gem, not another service to deploy.
+
+Your users already have questions. `livechat` gives them a chat bubble and
+gives you an inbox, inside the app you already run. Visitors write — signed
+in or not. Your team answers — together, every reply signed with its author.
+Nobody is around? Visitors leave an email and the conversation continues
+there. Every word stays in your database.
+
+- **A gem, not a platform.** `bundle add livechat`, one migration, one line
+  in your layout. No second app to deploy, no third-party script on your
+  pages, no per-seat pricing. Ever.
+- **Zero UI dependencies.** The widget is plain JavaScript and styles itself.
+  No Tailwind, no Stimulus, no importmap, no build step, no websockets to
+  configure. Works with Turbo Drive and strict nonce-based CSPs out of the box.
+- **Honest about response time.** The widget says "We usually reply within a
+  few hours" (you choose the words), not a fake "we're online". Email
+  notifications — both directions — keep slow conversations alive.
+- **A team sport.** Any authorized teammate answers any thread; each message
+  carries its author. You decide what visitors see — full names, first
+  names, or an anonymous "Support team".
+- **Real attribution.** Signed-in visitors are identified server-side against
+  your user records and keep their thread across devices. Guests get a
+  cookie, and keep their history when they sign up.
+- **26 languages.** The widget follows your app's locale, RTL included.
+
+## How it works
+
+1. Add `<%= livechat_tag %>` to your layout. A chat bubble appears
+   bottom-right (or open the panel from any element with
+   `data-livechat-open`, or `window.Livechat.open()`).
+2. A visitor writes. The message lands in `livechat_conversations` in your
+   database, and — if you configured it — in your team's email.
+3. Your team answers at the mount path (`/livechat`). Several people can
+   work the same thread; resolve it when done. A visitor writing again
+   reopens it — one thread per visitor, like a conversation, not tickets.
+4. The visitor sees the reply in the widget, or by email when they're gone.
+
+Realtime is polling, on purpose: ~4s while the panel is open, ~30s in the
+background, nothing at all for visitors who never wrote. No Action Cable,
+no Redis, no infrastructure. At support-chat volume you will not notice;
+your ops person will notice there is nothing new to run.
+
+## Requirements
+
+- Ruby >= 3.2
+- Rails >= 7.1
+
+## Installation
+
+```ruby
+# Gemfile
+gem "livechat"
+```
+
+```bash
+bundle install
+bin/rails generate livechat:install
+bin/rails db:migrate
+```
+
+The generator writes `config/initializers/livechat.rb`, creates the
+migration, and mounts the engine at `/livechat`. Then add the widget to your
+layout:
+
+```erb
+<%= livechat_tag %>
+```
+
+That's it. Visit any page, click the bubble, say hi. Answer yourself at
+`/livechat`.
+
+## Configuration
+
+Everything lives in `config/initializers/livechat.rb`; every option has a
+working default. The essentials:
+
+```ruby
+Livechat.configure do |config|
+  config.current_user = ->(request) { request.env["warden"]&.user }
+  config.authorize_agent = ->(request) { request.env["warden"]&.user&.admin? }
+  config.mailer_from = "chat@example.com"
+  config.agent_emails = -> { User.where(admin: true).pluck(:email) }
+  config.reply_time_text = "We usually reply within an hour."
+end
+```
+
+### Brand color
+
+```ruby
+config.accent_color = "#7c3aed"
+```
+
+One hex value restyles the launcher, header, visitor bubbles and send
+button; the widget picks black or white text automatically for contrast,
+in light and dark mode alike.
+
+### Who visitors talk to
+
+Replies are signed. What visitors see is up to you:
+
+```ruby
+config.agent_display_name = ->(label) { label.split.first }   # "Ada"
+config.agent_display_name = ->(_label) { "Support team" }     # anonymous
+```
+
+### Email, both directions
+
+When a visitor writes and nobody has read it, the team gets one email — one
+per unread stretch, not one per message. When an agent replies and the
+visitor is away, the visitor gets one email (signed-in visitors
+automatically, guests once they leave an address — the widget asks, gently).
+Requires `config.mailer_from`; team notifications also need
+`config.agent_emails`.
+
+For anything else, hook in:
+
+```ruby
+config.on_visitor_message = ->(message) { SlackNotifier.ping(message) }
+```
+
+## The inbox
+
+Browse at the mount path: open and resolved tabs, unread badges, one click
+into a thread. Reply (Cmd/Ctrl+Enter sends), resolve, reopen. The thread
+updates itself while you watch — and never reloads over a half-written
+reply. Gated by `config.authorize_agent` (development-only until you set it).
+
+## Widget API
+
+- `window.Livechat.open()` / `window.Livechat.close()`
+- Any element with `data-livechat-open` opens the panel on click
+- `<%= livechat_button %>` renders a plain, unstyled opener button
+- `config.show_launcher = false` hides the bubble entirely — bring your own
+  entry point
+
+## What it doesn't do
+
+No AI bots, no canned responses, no omnichannel (WhatsApp, Messenger…), no
+visitor tracking, no "powered by" badge. If you need a support platform,
+[Chatwoot](https://github.com/chatwoot/chatwoot) is excellent. If you need
+your users to be able to reach you from inside your Rails app — this is a
+gem's worth of exactly that.
+
+## Testing
+
+```bash
+bundle exec rake test
+bundle exec rubocop
+```
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+
+task default: :test

data/app/controllers/livechat/application_controller.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Livechat
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+
+    private
+
+    def current_visitor
+      return @current_visitor if defined?(@current_visitor)
+
+      @current_visitor = Livechat.config.current_user.call(request)
+    end
+
+    def current_visitor_id
+      current_visitor.respond_to?(:id) ? current_visitor.id.to_s : nil
+    end
+
+    def require_enabled
+      head :forbidden unless Livechat.enabled?(request)
+    end
+
+    # Server-side gate for the inbox. Default: development only.
+    def require_agent
+      return if Livechat.agent?(request)
+
+      render plain: 'Forbidden. Set Livechat.config.authorize_agent to grant access.',
+             status: :forbidden
+    end
+
+    # Replies are attributed to whoever config.current_user resolves. When an
+    # inbox is protected by something user-less (HTTP basic, a VPN), replies
+    # still work — anonymously, as "Support".
+    def current_agent_id
+      current_visitor_id || '0'
+    end
+
+    def current_agent_label
+      label = (Livechat.config.agent_label.call(current_visitor).presence if current_visitor)
+      label || I18n.t(:team, scope: :livechat, default: 'Support')
+    end
+
+    def render_rate_limited
+      message = I18n.t('livechat.error_rate_limited',
+                       default: 'Too many messages. Please wait a moment and try again.')
+      render json: { errors: [message] }, status: :too_many_requests
+    end
+
+    # Guests get a permanent random token — their key to the conversation
+    # across visits. Signed-in visitors are keyed by id and only need the
+    # cookie to carry a guest history into their account.
+    def visitor_token
+      cookies[:livechat_vid]
+    end
+
+    def ensure_visitor_token
+      visitor_token.presence || begin
+        token = SecureRandom.base58(24)
+        cookies.permanent[:livechat_vid] = { value: token, httponly: true, same_site: :lax }
+        token
+      end
+    end
+
+    # A guest who signed in keeps their thread: adopt cookie-token
+    # conversations into the account, then the cookie no longer matters.
+    def claim_guest_conversations
+      return unless current_visitor_id && visitor_token
+
+      Conversation.claim!(
+        visitor_token: visitor_token,
+        visitor_id: current_visitor_id,
+        visitor_label: Livechat.config.visitor_label.call(current_visitor).presence
+      )
+    end
+  end
+end

data/app/controllers/livechat/conversations_controller.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Livechat
+  # The inbox. Every action is gated by config.authorize_agent; any
+  # authorized teammate can read and answer any thread — it's a shared line,
+  # not an assignment queue.
+  class ConversationsController < ApplicationController
+    before_action :require_agent
+    before_action :set_conversation, except: :index
+    layout 'livechat/application'
+
+    PER_PAGE = 50
+
+    def index
+      @status = Conversation::STATUSES.include?(params[:status]) ? params[:status] : 'open'
+      @counts = Conversation.group(:status).count
+      @offset = params[:offset].to_i.clamp(0, 1_000_000)
+
+      scope = Conversation.where(status: @status).recent_first
+      page = scope.offset(@offset).limit(PER_PAGE + 1).to_a
+      @more = page.size > PER_PAGE
+      @conversations = page.first(PER_PAGE)
+
+      # Unread badges for the whole page in one query.
+      @unread = Message.from_visitor.unread
+                       .where(conversation_id: @conversations.map(&:id))
+                       .group(:conversation_id).count
+    end
+
+    def show
+      @messages = @conversation.messages.chronological.to_a
+      @conversation.mark_read_for_agent!
+    end
+
+    # Polled by dashboard.js: has anything new arrived in this thread?
+    def poll
+      render json: { latest: @conversation.messages.maximum(:id).to_i,
+                     status: @conversation.status }
+    end
+
+    def resolve
+      @conversation.resolve_by!(current_agent_label)
+      redirect_to conversation_path(@conversation)
+    end
+
+    def reopen
+      @conversation.reopen_by!(current_agent_label)
+      redirect_to conversation_path(@conversation)
+    end
+
+    private
+
+    def set_conversation
+      @conversation = Conversation.find(params[:id])
+    end
+  end
+end

data/app/controllers/livechat/messages_controller.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Livechat
+  class MessagesController < ApplicationController
+    before_action :require_agent
+
+    def create
+      conversation = Conversation.find(params[:conversation_id])
+      message = conversation.post_agent_message!(
+        body: params[:body].to_s.strip,
+        agent_id: current_agent_id,
+        agent_label: current_agent_label
+      )
+      Notifications.agent_message(message)
+
+      redirect_to conversation_path(conversation, anchor: "message-#{message.id}")
+    rescue ActiveRecord::RecordInvalid => e
+      redirect_to conversation_path(conversation), alert: e.record.errors.full_messages.first
+    end
+  end
+end

data/app/controllers/livechat/visitor_controller.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Livechat
+  # The widget's API. Every action is scoped to the requesting visitor — the
+  # signed-in user's id, or the guest cookie token — so there is nothing to
+  # enumerate and no id to leak. Gated by config.enabled and rate-limited.
+  class VisitorController < ApplicationController
+    before_action :require_enabled
+    before_action :claim_guest_conversations
+
+    if respond_to?(:rate_limit) && Livechat.config.rate_limit
+      rate_limit(**Livechat.config.rate_limit,
+                 only: %i[create email],
+                 with: -> { render_rate_limited })
+    end
+
+    # GET widget/conversation(?after=<id>) — the widget's single source of
+    # truth: thread status, unread count for the launcher badge, and messages
+    # (all of them, or only those after the given id when polling).
+    def show
+      conversation = find_conversation
+      return render json: empty_state unless conversation
+
+      messages = conversation.messages.chronological
+      messages = messages.after_id(params[:after]) if params[:after].present?
+
+      render json: {
+        status: conversation.status,
+        unread: conversation.messages.from_agent.unread.count,
+        email: conversation.visitor_email.present?,
+        messages: messages.map(&:as_widget_json)
+      }
+    end
+
+    # POST widget/messages — first message starts the thread; writing into a
+    # resolved thread reopens it.
+    def create
+      message = nil
+      # One transaction, so an invalid first message never leaves an empty
+      # conversation behind.
+      ActiveRecord::Base.transaction do
+        conversation = find_conversation || start_conversation
+        message = conversation.post_visitor_message!(params[:body].to_s.strip)
+      end
+      refresh_context(message.conversation)
+      Notifications.visitor_message(message)
+
+      render json: { message: message.as_widget_json }, status: :created
+    rescue ActiveRecord::RecordInvalid => e
+      render json: { errors: e.record.errors.full_messages }, status: :unprocessable_entity
+    end
+
+    # POST widget/email — a guest leaves an address so replies reach them
+    # when they're gone.
+    def email
+      conversation = find_conversation
+      return head :not_found unless conversation
+
+      if conversation.update(visitor_email: params[:email].to_s.strip.presence)
+        head :no_content
+      else
+        render json: { errors: conversation.errors.full_messages }, status: :unprocessable_entity
+      end
+    end
+
+    # POST widget/read — the visitor opened the panel and saw the replies.
+    def read
+      find_conversation&.mark_read_for_visitor!
+      head :no_content
+    end
+
+    private
+
+    def find_conversation
+      Conversation.for_visitor(visitor_id: current_visitor_id, visitor_token: visitor_token)
+    end
+
+    def start_conversation
+      Conversation.create!(
+        visitor_id: current_visitor_id,
+        visitor_token: current_visitor_id ? visitor_token : ensure_visitor_token,
+        visitor_label: visitor_label,
+        visitor_email: (current_visitor.try(:email).presence if current_visitor),
+        page_url: params[:page_url].to_s.first(255).presence,
+        locale: params[:locale].to_s.first(10).presence
+      )
+    end
+
+    def visitor_label
+      return unless current_visitor
+
+      Livechat.config.visitor_label.call(current_visitor).presence
+    end
+
+    # page_url and locale track the visitor's LAST message, not the first —
+    # "where are they stuck right now" is what an answering agent needs.
+    def refresh_context(conversation)
+      updates = {}
+      updates[:page_url] = params[:page_url].to_s.first(255) if params[:page_url].present?
+      updates[:locale] = params[:locale].to_s.first(10) if params[:locale].present?
+      conversation.update_columns(updates) if updates.any?
+    end
+
+    def empty_state
+      { status: nil, unread: 0, email: false, messages: [] }
+    end
+  end
+end

data/app/controllers/livechat/widgets_controller.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Livechat
+  # Serves the widget JavaScript as a plain same-origin script. Same-origin
+  # matters: under a `script-src 'self'` (or nonce-based) CSP, an external
+  # script from the app's own host is always allowed — including when Turbo
+  # Drive swaps the <body> and re-runs body scripts under the *original*
+  # page's CSP header, where a freshly minted inline nonce would be refused.
+  class WidgetsController < ApplicationController
+    # The script is static and carries no user data; without this, Rails'
+    # cross-origin JavaScript guard refuses to serve it to a plain
+    # <script src> request.
+    skip_forgery_protection
+
+    # The script URLs carry a content fingerprint (?v=<md5>), so stale code
+    # is structurally impossible: new code means a new URL. The canonical
+    # fingerprinted URL is immutable and gets long-lived caching; anything
+    # else only ETag-revalidates.
+    def show
+      serve(Widget.javascript, Widget.fingerprint)
+    end
+
+    def dashboard
+      serve(Widget.dashboard_javascript, Widget.dashboard_fingerprint)
+    end
+
+    private
+
+    def serve(source, fingerprint)
+      expires_in 1.year, public: true if params[:v] == fingerprint
+      return unless stale?(etag: [Livechat::VERSION, fingerprint])
+
+      render plain: source, content_type: 'text/javascript'
+    end
+  end
+end

data/app/helpers/livechat/widget_helper.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Livechat
+  # Included into the host's ActionView. Drop `<%= livechat_tag %>` before
+  # </body> in your layout; it renders nothing unless chat is enabled for the
+  # request. The widget shows a floating launcher (unless show_launcher is
+  # off) and also opens from any element carrying `data-livechat-open`, or
+  # from `window.Livechat.open()`.
+  module WidgetHelper
+    def livechat_tag
+      return unless Livechat.enabled?(request)
+
+      Widget.snippet(
+        locale: I18n.locale,
+        authenticated: livechat_visitor.present?,
+        nonce: (content_security_policy_nonce if respond_to?(:content_security_policy_nonce))
+      ).html_safe
+    end
+
+    # A plain, unstyled <button> that opens the chat — it picks up the host's
+    # own styles. Put it anywhere on a page that also renders livechat_tag.
+    def livechat_button(label: nil, **)
+      return unless Livechat.enabled?(request)
+
+      label ||= I18n.t(:launcher, scope: :livechat, default: 'Chat with us')
+      tag.button(label, type: 'button', 'data-livechat-open': '', **)
+    end
+
+    private
+
+    def livechat_visitor
+      return @livechat_visitor if defined?(@livechat_visitor)
+
+      @livechat_visitor = Livechat.config.current_user.call(request)
+    end
+  end
+end

data/app/mailers/livechat/mailer.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Livechat
+  # The two built-in notification emails. Plain text, no branding — they are
+  # nudges back into the conversation, not newsletters. Both require
+  # config.mailer_from; the callers in Livechat::Notifications enforce the
+  # rest of the conditions (recipients present, first unread message).
+  class Mailer < ActionMailer::Base
+    # To the team: a visitor wrote and nobody has read it.
+    def new_visitor_message(message)
+      @message = message
+      @conversation = message.conversation
+      @inbox_url = inbox_url(@conversation)
+
+      mail from: Livechat.config.mailer_from,
+           to: Livechat.config.agent_email_list,
+           subject: I18n.t('livechat.mail.visitor_subject',
+                           name: @conversation.display_name, app: Livechat.app_name,
+                           default: '%{name} wrote to you on %{app}')
+    end
+
+    # To the visitor: an agent replied while they were away.
+    def new_agent_reply(message)
+      @message = message
+      @conversation = message.conversation
+
+      mail from: Livechat.config.mailer_from,
+           to: @conversation.visitor_email,
+           subject: I18n.t('livechat.mail.reply_subject',
+                           name: message.public_label, app: Livechat.app_name,
+                           default: '%{name} replied to you on %{app}')
+    end
+
+    private
+
+    # An absolute link to the inbox needs a host. Reuse the one hosts already
+    # configure for Action Mailer (Devise needs it too); without one, the
+    # email simply carries no link.
+    def inbox_url(conversation)
+      host = default_url_options[:host] || ActionMailer::Base.default_url_options[:host]
+      return unless host
+
+      Livechat::Engine.routes.url_helpers.conversation_url(
+        conversation, host: host, **default_url_options.except(:host),
+                      script_name: Livechat.config.mount_path.chomp('/')
+      )
+    rescue StandardError
+      nil
+    end
+  end
+end

data/app/models/livechat/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Livechat
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end