support_desk 0.1.0

data/lib/support_desk/context_card.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # Everything an agent needs next to the transcript, as plain Ruby: what
+  # the case is about, what state that thing is in, who is asking, and
+  # where to go to do something about it.
+  #
+  #   card = ticket.context_card
+  #   card.title          # "Viaje Sevilla → Granada · 20 sep"
+  #   card.status         # "Completado"
+  #   card.pairs          # { "Conductor" => "Lucía G.", "Plazas" => 3 }
+  #   card.subject_url    # "/madmin/rides/…"
+  #   card.requester_name # "Alice"
+  #
+  # No view dependency at all — render it in ERB, a JSON API, or a Telegram
+  # message.
+  class ContextCard
+    attr_reader :ticket
+
+    # The card for one ticket.
+    def initialize(ticket)
+      @ticket = ticket
+    end
+
+    # What the case is about, and what to call it.
+    def subject = ticket.subject
+
+    # What to put at the top of the card.
+    def title = ticket.label
+
+    # The subject's own status pill, when it has one.
+    def status = subject&.support_status
+
+    # Key/value pairs the host chose to show agents.
+    def pairs
+      subject&.support_context || {}
+    end
+
+    # Where to open the subject in the host's admin, or nil.
+    def subject_url = subject&.support_url
+
+    # The topic, and the whole branch spelled out.
+    def topic = ticket.topic
+
+    # The whole branch spelled out ("Billing › Invoice").
+    def topic_label = ticket.topic&.full_label
+
+    # Who is asking, as the console should show them.
+    def requester = ticket.requester
+
+    # The requester as the console should show them: a display name, and
+    # an avatar if the host has one.
+    def requester_name
+      Chats.display_name_for(requester)
+    end
+
+    # Anything image_tag accepts, or nil.
+    def requester_avatar
+      Chats.avatar_for(requester)
+    end
+
+    # When this requester joined — context for "is this a new user?".
+    def requester_since = requester.try(:created_at)
+
+    # How many open cases this requester has right now, this one included.
+    def requester_open_tickets
+      Ticket.not_closed.where(requester: requester).count
+    end
+
+    # The same card as a Hash, for a JSON console.
+    def to_h
+      {
+        title: title,
+        status: status,
+        topic: topic&.path,
+        topic_label: topic_label,
+        pairs: pairs,
+        subject_url: subject_url,
+        requester: {
+          name: requester_name,
+          since: requester_since,
+          open_tickets: requester_open_tickets
+        }
+      }
+    end
+
+    # The card, in one line.
+    def inspect = "#<SupportDesk::ContextCard #{title.inspect}>"
+  end
+end

data/lib/support_desk/current.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "active_support/current_attributes"
+
+module SupportDesk
+  # The ambient actor for the current request or job. Every ticket transition
+  # takes `by:`; when it's omitted, this is where it falls back to — the user
+  # engine sets it from `current_requester`, the console concern from
+  # `current_agent`:
+  #
+  #   SupportDesk::Current.actor = current_user
+  #   ticket.close!                        # => by: current_user
+  #
+  # Nothing is set for you. When both `by:` and this are empty, transitions
+  # raise SupportDesk::ActorMissing rather than writing an unattributed row —
+  # a support timeline nobody signed is worth less than no timeline.
+  class Current < ActiveSupport::CurrentAttributes
+    # The person (or bot) acting: an agent in the console, a requester in the
+    # engine. `:system` is a legitimate value for jobs and sweeps.
+    attribute :actor
+
+    # The current ActionDispatch::Request, when there is one. Only ever used
+    # to enrich event payloads (IP, user agent) — never to authorize.
+    attribute :request
+  end
+end

data/lib/support_desk/doctor.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # Everything that can only be checked against a running app: the
+  # configuration the initializer wrote, the chats seams the gem is built
+  # on, and the invariants the data is supposed to keep.
+  #
+  #   SupportDesk.doctor.print      # in a console
+  #   exit 1 unless SupportDesk.doctor.ok?   # in CI
+  #
+  # Checks never raise: a doctor that blows up is a doctor nobody runs.
+  class Doctor
+    # One finding. :ok, :warn (worth fixing, nothing is broken) or :fail
+    # (support is not working right now).
+    Check = Struct.new(:name, :status, :message, keyword_init: true) do
+      def ok? = status == :ok
+      # Worth fixing, and actually broken.
+      def warn? = status == :warn
+      def fail? = status == :fail
+
+      # "✓ name message" — one finding, printable.
+      def to_s
+        icon = { ok: "✓", warn: "!", fail: "✗" }.fetch(status)
+        [ icon, name, message ].compact.join(" ")
+      end
+    end
+
+    # What `SupportDesk.doctor` hands back.
+    class Report
+      attr_reader :checks
+
+      # A report over the checks that were run.
+      def initialize(checks)
+        @checks = checks
+      end
+
+      # True when nothing failed. Warnings don't fail a build.
+      def ok? = failures.empty?
+
+      # The checks worth acting on: failures break support, warnings don't.
+      def failures = checks.select(&:fail?)
+      def warnings = checks.select(&:warn?)
+
+      # Every check, one per line, with the verdict last.
+      def to_s
+        lines = checks.map(&:to_s)
+        lines << (ok? ? "support_desk is healthy (#{warnings.size} warning(s))" : "#{failures.size} check(s) failed")
+        lines.join("\n")
+      end
+
+      # Print the report and return whether it passed — the one line to
+      # put in a CI step.
+      def print(io = $stdout)
+        io.puts(to_s)
+        ok?
+      end
+
+      # The verdict, in one line.
+      def inspect = "#<SupportDesk::Doctor::Report #{ok? ? "ok" : "#{failures.size} failed"}>"
+    end
+
+    # Run every check and hand back the report.
+    def self.run = new.run
+
+    # Run every check and hand back the report.
+    def run
+      checks = []
+      checks.concat(configuration_checks)
+      checks.concat(seam_checks)
+      checks.concat(invariant_checks)
+      Report.new(checks)
+    end
+
+    private
+
+    def configuration_checks
+      checks = []
+
+      checks << check("requester_class") do
+        klass = SupportDesk.config.requester_class.safe_constantize
+        next fail_with("#{SupportDesk.config.requester_class} doesn't exist") unless klass
+        unless klass.respond_to?(:support_desk_requester_options)
+          next fail_with("#{klass} is missing `has_support_tickets`")
+        end
+        next fail_with("#{klass} is missing `acts_as_messager` (chats)") unless klass.include?(Chats::Messager)
+
+        ok_with("#{klass} asks for support")
+      end
+
+      checks << check("agents") do
+        pool = SupportDesk.config.default_desk.agent_pool
+        next warn_with("no agent pool configured — set `config.agents { User.admin }`") if pool.nil?
+
+        ok_with("#{pool.respond_to?(:count) ? pool.count : pool.size} agent(s)")
+      end
+
+      SupportDesk.config.desks.each_value do |desk|
+        checks << check("topics (#{desk.key})") do
+          tree = desk.topics
+          next warn_with("no topics configured — every ticket lands on the free-form leaf") if tree.empty?
+          next warn_with("no free-form topic: add `other` to the topics block") unless tree.free_form?
+
+          ok_with("#{tree.count} topic(s), #{tree.leaves.size} leaf/leaves")
+        end
+
+        checks << check("supportables (#{desk.key})") do
+          missing = desk.topics.about_class_names.reject do |name|
+            klass = name.safe_constantize
+            klass.respond_to?(:supportable?) && klass.supportable?
+          end
+          next fail_with("not supportable: #{missing.join(", ")}") if missing.any?
+
+          ok_with("every about: class is supportable")
+        end
+      end
+
+      checks << check("engine mount") do
+        path = SupportDesk.root_path
+        next warn_with("SupportDesk::Engine isn't mounted — requesters have nowhere to write") if path.nil?
+
+        ok_with("mounted at #{path}")
+      end
+
+      checks << check("parent controllers") do
+        missing = [ SupportDesk.config.parent_controller, SupportDesk.config.console_parent_controller ].reject do |name|
+          name.safe_constantize
+        end
+        next fail_with("#{missing.join(", ")} doesn't exist") if missing.any?
+
+        ok_with("resolved")
+      end
+
+      checks
+    end
+
+    # The chats seams this gem is built on. A host on the wrong chats
+    # version should hear it from `doctor`, not from a NoMethodError in
+    # production.
+    def seam_checks
+      [
+        check("chats subscribers") do
+          next fail_with("this chats doesn't expose `Chats.on` — support_desk needs chats ~> 0.2") unless
+            Chats.respond_to?(:on)
+
+          ok_with("Chats.on available")
+        end,
+        check("chats authorship") do
+          next fail_with("chats_messages has no author column — run `rails g chats:upgrade`") unless
+            Chats::Message.column_names.include?("author_id")
+
+          ok_with("messages can be signed")
+        end,
+        check("desk messager") do
+          next fail_with("SupportDesk::Desk isn't a chats messager") unless Desk.include?(Chats::Messager)
+
+          ok_with("the desk converses")
+        end
+      ]
+    end
+
+    def invariant_checks
+      return [ check("database") { warn_with("support_desk tables are missing — run rails db:migrate") } ] unless
+        tables?
+
+      [
+        check("conversations") do
+          orphans = Ticket.where(conversation_id: nil).count
+          next fail_with("#{orphans} ticket(s) without a conversation") if orphans.positive?
+
+          ok_with("every ticket has one")
+        end,
+        check("assignments") do
+          duplicated = Assignment.open.group(:ticket_id).having("COUNT(*) > 1").count.size
+          next fail_with("#{duplicated} ticket(s) with more than one open assignment") if duplicated.positive?
+
+          ok_with("at most one open assignment per ticket")
+        end,
+        check("assignee pointers") do
+          # A CLOSED ticket keeps its assignee with no open assignment row:
+          # that is the record of who dealt with it, not a live seat.
+          mismatched = Ticket.not_closed.assigned.where.not(
+            id: Assignment.open.select(:ticket_id)
+          ).count
+          next fail_with("#{mismatched} ticket(s) whose assignee has no open assignment") if mismatched.positive?
+
+          ok_with("assignee matches the open assignment")
+        end,
+        check("awaiting") do
+          stale = Ticket.awaiting_reply.where("last_agent_message_at > last_requester_message_at").count
+          next fail_with("#{stale} ticket(s) waiting on the desk after the desk already answered") if stale.positive?
+
+          ok_with("awaiting agrees with the transcript")
+        end,
+        check("references") do
+          duplicated = Ticket.group(:reference).having("COUNT(*) > 1").count.size
+          next fail_with("#{duplicated} duplicated reference(s)") if duplicated.positive?
+
+          ok_with("references are unique")
+        end
+      ]
+    end
+
+    def tables?
+      ActiveRecord::Base.connection.table_exists?(Ticket.table_name)
+    rescue StandardError
+      false
+    end
+
+    def check(name)
+      status, message = yield
+      Check.new(name: name, status: status, message: message)
+    rescue StandardError => e
+      Check.new(name: name, status: :fail, message: "#{e.class}: #{e.message}")
+    end
+
+    def ok_with(message) = [ :ok, message ]
+    def warn_with(message) = [ :warn, message ]
+    def fail_with(message) = [ :fail, message ]
+  end
+end

data/lib/support_desk/engine.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module SupportDesk
+  # The mountable engine: wires autoloading, migrations, locales, the
+  # ActiveRecord macros, and boot-time configuration into the host app.
+  #
+  #   mount SupportDesk::Engine => "/support"
+  #
+  # The requester-facing screens live here; the agent console is BYOUI
+  # (query objects, presenters and a generator — see the README).
+  class Engine < ::Rails::Engine
+    isolate_namespace SupportDesk
+
+    # -------------------------------------------------------------------------
+    # Zeitwerk: the gem keeps its ActiveRecord models under
+    # lib/support_desk/models (the same layout as chats and moderate) so the
+    # whole domain ships in lib/ and the engine's app/ tree only holds the
+    # web layer. For that to autoload we manage the loader by hand:
+    #
+    #   - push_dir(lib/support_desk, namespace: SupportDesk) makes
+    #     lib/support_desk/models/... autoloadable under the SupportDesk
+    #     namespace.
+    #   - collapse(models) + collapse(models/concerns) mean those files
+    #     define SupportDesk::Ticket, not SupportDesk::Models::Ticket.
+    #   - The SPINE files are required explicitly by lib/support_desk.rb at
+    #     boot (the configuration DSL has to exist before any initializer
+    #     runs), so they must be IGNORED by the loader or Zeitwerk would
+    #     complain about unmanaged constants.
+    # -------------------------------------------------------------------------
+    LIB_ROOT = File.expand_path("..", __dir__)
+    SUPPORT_DESK_LIB = File.expand_path("support_desk", LIB_ROOT)
+
+    ZEITWERK_IGNORED = %w[
+      version.rb errors.rb events.rb topic.rb topic_tree.rb configuration.rb current.rb macros.rb engine.rb
+      console.rb console_routes.rb console_engine.rb
+    ].freeze
+
+    initializer "support_desk.autoload", before: :set_autoload_paths do
+      loader = Rails.autoloaders.main
+
+      ZEITWERK_IGNORED.each do |file|
+        path = File.join(SUPPORT_DESK_LIB, file)
+        loader.ignore(path) if File.exist?(path)
+      end
+
+      %w[models models/concerns].each do |dir|
+        path = File.join(SUPPORT_DESK_LIB, dir)
+        loader.collapse(path) if File.directory?(path)
+      end
+
+      loader.push_dir(SUPPORT_DESK_LIB, namespace: SupportDesk)
+    end
+
+    config.eager_load_paths << SUPPORT_DESK_LIB
+
+    # Make the gem's migrations runnable from the host without copying. The
+    # install generator still copies a host-owned migration, which is the
+    # recommended path; this mainly serves the dummy app.
+    initializer "support_desk.migrations" do |app|
+      unless app.root.to_s == root.to_s
+        config.paths["db/migrate"].expanded.each do |path|
+          app.config.paths["db/migrate"] << path
+        end
+      end
+    end
+
+    # Expose `has_support_tickets` / `supportable` / `acts_as_support_agent`
+    # on every AR model.
+    initializer "support_desk.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        extend SupportDesk::Macros
+      end
+    end
+
+    # Serve the bundled stylesheet the requester-facing views link (propshaft
+    # or sprockets — both honour config.assets.paths). A host that ejects and
+    # restyles the views simply stops rendering `support_desk_styles`.
+    initializer "support_desk.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/assets/stylesheets")
+        # Sprockets compiles only what is declared; without this the host
+        # 404s the stylesheet in production while Propshaft (which serves
+        # everything on the path) works fine, so the gap only shows up on
+        # somebody else's deploy.
+        app.config.assets.precompile << "support_desk.css" if app.config.assets.respond_to?(:precompile)
+      end
+    end
+
+    # The gem's locale files (en, es) ship through Rails::Engine's own
+    # :add_locales initializer, which picks up every engine's config/locales
+    # automatically — and deliberately NOT through a manual
+    # `app.config.i18n.load_path +=` on top of it.
+    #
+    # That manual append is not merely redundant, it INVERTS the contract.
+    # Railtie paths are unshifted ahead of everything in load_path, so an
+    # appended copy of these files lands AFTER the host's own locales and
+    # silently overrides them: a host that rewords `support_desk.queue.tabs
+    # .awaiting` in its own es.yml would keep reading ours. Measured before
+    # this was removed: the gem's file sat in load_path 14 times and the
+    # host's override lost.
+    #
+    # Gem first, host last. `clickwrap` learned this the same way and its
+    # engine carries the same note.
+
+    # Keep `awaiting`, the SLA clocks and reopen-on-reply true by listening
+    # to chats. One subscriber, registered once, for every channel a message
+    # can arrive through.
+    initializer "support_desk.chats_subscribers" do
+      SupportDesk.subscribe_to_chats!
+    end
+
+    # The checks that need the host's own classes loaded — the requester
+    # class, and every `about:` class named in a topic tree. In to_prepare
+    # (not an initializer) so they re-run after every code reload, which is
+    # exactly when a model stops being `supportable`.
+    config.to_prepare do
+      # Touch the helper so its bottom-of-file on_load(:action_view) hook
+      # registers even when no engine code has been referenced yet. Without
+      # this, `link_to_support` is undefined in every host that does not
+      # eager load — which is every host in development.
+      # (Assigned to appease Lint/Void — the constant REFERENCE is the point.)
+      _loaded = SupportDesk::EngineHelper
+
+      # Touch the desk for the same reason, on the CHATS side. `acts_as_messager`
+      # registers a class with chats when that class LOADS, and `Chats::Inbox`
+      # reads that registry (`Chats.grouped_messager_types`) to decide which
+      # messager types fold into one inbox row. Under lazy autoloading nothing
+      # has referenced SupportDesk::Desk by the time a requester opens their
+      # inbox, so the registry is empty, the stacking prefilter matches nothing,
+      # and every support conversation renders as its own row — the exact noise
+      # the grouped row exists to prevent. Eager-loading hosts (production)
+      # never see it; development does, and "works in prod, wrong locally" is
+      # the worst shape for a bug. Found by the CarHey integration (#2).
+      _desk = SupportDesk::Desk
+
+      SupportDesk.config.validate_classes! if SupportDesk.configured?
+    end
+  end
+end

data/lib/support_desk/errors.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # Base class for every error this gem raises, so hosts can
+  # `rescue SupportDesk::Error` to catch anything support-specific.
+  class Error < StandardError; end
+
+  # Raised by `SupportDesk.configure`, by the validating setters, and by the
+  # boot-time checks when the configuration can't work as written.
+  class ConfigurationError < Error; end
+
+  # Raised when a transition was given no `by:` and nothing set
+  # `SupportDesk::Current.actor`. Pass `by: :system` from jobs.
+  class ActorMissing < Error; end
+
+  # Raised when the record handed to an agent-side operation isn't an eligible
+  # agent (no `acts_as_support_agent`, or its `if:` said no).
+  class NotAnAgent < Error; end
+
+  # Raised by `hand_off!` when the actor doesn't currently hold the ticket.
+  class NotTheAssignee < Error; end
+
+  # Raised when policy forbids the attempted action — a drop-in reply under
+  # `reply_policy = :assignee_only`, a requester acting on someone else's
+  # ticket, a subject the requester may not talk about.
+  class NotAllowed < Error; end
+
+  # Raised when a transition can't happen from the ticket's current state
+  # (releasing a closed ticket, assigning one).
+  class InvalidTransition < Error; end
+
+  # Raised when the conversation behind a ticket is locked for writing —
+  # a closed ticket on a desk configured `closed_tickets: :locked`.
+  # A subclass of InvalidTransition, so `rescue InvalidTransition` still
+  # catches it and the specific name is there when you want it.
+  class Locked < InvalidTransition; end
+
+  # Raised when a topic path isn't in the desk's tree.
+  class UnknownTopic < Error; end
+
+  # Raised when a record was offered as a ticket subject without `supportable`.
+  class NotSupportable < Error; end
+
+  # Raised when a requester trips `config.open_rate_limit`.
+  class RateLimited < Error; end
+
+  # Raised when a requester is already at `config.max_open_tickets`.
+  class TooManyOpenTickets < Error; end
+end

data/lib/support_desk/events.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # The gem emits; the host delivers. Every domain moment goes through one
+  # multi-subscriber, error-isolated dispatcher:
+  #
+  #   SupportDesk.on(:ticket_opened)     { |ticket|    Support::TicketNotifier.deliver(ticket.agents_to_notify) }
+  #   SupportDesk.on(:requester_replied) { |ticket, m| … }
+  #   SupportDesk.on(:ticket_transitioned) { |ticket, kind, by:, request:, payload:| AuditLog.log(…) }
+  #
+  # Three guarantees worth knowing:
+  #
+  # 1. **After commit.** Events fire once the transition they describe is
+  #    durable, so a subscriber never reads uncommitted state and never
+  #    enqueues a job that races the write.
+  # 2. **Isolated.** A subscriber that raises is reported through
+  #    `Rails.error` and the next subscriber still runs. A broken notifier
+  #    can't roll back a ticket.
+  # 3. **Mirrored.** Every event is also published on ActiveSupport
+  #    ::Notifications as `"<event>.support_desk"` for APM and hosts that
+  #    prefer that bus.
+  module Events
+    # The catalogue. Keys are event names; values document the arguments
+    # subscribers receive (see 09-events-and-notifications).
+    CATALOGUE = {
+      ticket_opened: "ticket",
+      requester_replied: "ticket, message",
+      agent_replied: "ticket, message",
+      ticket_assigned: "ticket, assignment",
+      ticket_handed_off: "ticket, assignment, from:, note:",
+      ticket_released: "ticket, from:, reason:",
+      ticket_closed: "ticket, by:",
+      ticket_reopened: "ticket, by:",
+      ticket_topic_changed: "ticket, from:, to:, by:",
+      subject_attached: "ticket, subject, by:",
+      note_added: "ticket, event",
+      ticket_transitioned: "ticket, kind, by:, request:, payload:"
+    }.freeze
+
+    # One registered callable, and the key it can be replaced under.
+    Subscriber = Struct.new(:key, :callable) do
+      def call(*args, **kwargs) = callable.call(*args, **kwargs)
+    end
+
+    # Subscribe to an event. Multiple subscribers per event are the point;
+    # they run in registration order and never see each other's exceptions.
+    # Returns the block, so a host can keep the handle.
+    #
+    # Pass `key:` from anywhere that runs more than once — a `to_prepare`
+    # block, an engine initializer — and re-registering REPLACES that
+    # subscriber in place instead of stacking a second copy on every code
+    # reload.
+    def on(event, key: nil, &block)
+      event = event.to_sym
+      unless CATALOGUE.key?(event)
+        raise ConfigurationError,
+              "unknown event #{event.inspect} — support_desk emits #{CATALOGUE.keys.map(&:inspect).join(", ")}"
+      end
+      raise ConfigurationError, "SupportDesk.on(#{event.inspect}) needs a block" unless block
+
+      entry = Subscriber.new(key, block)
+      list = subscribers[event]
+      existing = key && list.index { |subscriber| subscriber.key == key }
+      existing ? list[existing] = entry : list << entry
+      block
+    end
+
+    # Drop a keyed subscriber. Mostly for tests and for hosts that wire
+    # support up and down around a block.
+    def off(event, key)
+      subscribers[event.to_sym].reject! { |subscriber| subscriber.key == key }
+      self
+    end
+
+    # Everything registered, as { event => [block, …] }. Mutable on purpose:
+    # `reset!` empties it between tests.
+    def subscribers
+      @subscribers ||= Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    # Fire +event+ now. Internal — the models call this; hosts subscribe.
+    def emit(event, *args, **kwargs) # :nodoc:
+      event = event.to_sym
+
+      instrument(event, *args, **kwargs)
+
+      subscribers[event].each do |subscriber|
+        subscriber.call(*args, **kwargs)
+      rescue StandardError => e
+        report_subscriber_error(e, event)
+      end
+
+      nil
+    end
+
+    # Fire +event+ once the surrounding transaction commits (immediately when
+    # there is none). Every transition emits through here.
+    def emit_after_commit(event, *args, **kwargs) # :nodoc:
+      if defined?(ActiveRecord) && ActiveRecord.respond_to?(:after_all_transactions_commit)
+        ActiveRecord.after_all_transactions_commit { emit(event, *args, **kwargs) }
+      else
+        emit(event, *args, **kwargs)
+      end
+    end
+
+    private
+
+    def instrument(event, *args, **kwargs)
+      return unless defined?(ActiveSupport::Notifications)
+
+      ActiveSupport::Notifications.instrument("#{event}.support_desk", args: args, **kwargs)
+    end
+
+    def report_subscriber_error(error, event)
+      if defined?(Rails) && Rails.respond_to?(:error) && Rails.error
+        Rails.error.report(error, handled: true, source: "support_desk", context: { event: event })
+      else
+        logger&.error("[support_desk] subscriber raised on #{event}: #{error.class}: #{error.message}")
+      end
+    end
+  end
+end