support_desk 0.1.0

data/app/assets/stylesheets/support_desk.css

@@ -0,0 +1,242 @@
+/*
+ * support_desk — bundled default styles for the requester-facing screens.
+ *
+ * Self-contained for the same reason chats' are: an engine's views can't
+ * lean on the host's CSS framework, because a Tailwind host never scans gem
+ * view files and the utility classes used here would simply not exist in its
+ * build. Semantic support-desk-* classes + plain modern CSS work in ANY host
+ * with zero build integration.
+ *
+ * The list and its rows deliberately reuse chats' own classes (.chats-row,
+ * .chats-badge, .chats-empty) — a support case IS a conversation, and it
+ * should look like one. This file only adds what chats has no opinion about:
+ * the wizard, the choices, the composer and the doors.
+ *
+ * Theme with CSS variables (chats' are inherited where they overlap):
+ *
+ *   :root {
+ *     --support-desk-accent: #facc15;
+ *     --support-desk-accent-contrast: #111827;
+ *   }
+ *
+ * `rails g support_desk:views` ejects the templates into your app — restyle
+ * them with your own framework and skip this file (it's linked by the views
+ * through the support_desk_styles helper).
+ */
+
+:root {
+  --support-desk-card-bg: #ffffff;
+  --support-desk-accent: var(--chats-accent, #111827);
+  --support-desk-accent-contrast: var(--chats-accent-contrast, #ffffff);
+  --support-desk-surface: var(--chats-surface, #f3f4f6);
+  --support-desk-border: var(--chats-border, rgba(0, 0, 0, 0.08));
+  --support-desk-text: var(--chats-text, #111827);
+  --support-desk-text-muted: var(--chats-text-muted, #6b7280);
+  --support-desk-radius: var(--chats-radius, 1.1rem);
+}
+
+.support-desk { color: var(--support-desk-text); }
+
+/*
+ * Every box this file draws sizes itself INCLUDING its padding and border.
+ * A gem cannot assume the host ships a `* { box-sizing: border-box }` reset,
+ * and without it `width: 100%` plus 1rem of padding is 2rem wider than the
+ * screen — which on the composer, the one screen this gem exists for, means
+ * the page scrolls sideways on a phone.
+ */
+.support-desk,
+.support-desk *,
+.support-desk *::before,
+.support-desk *::after,
+.support-desk-door,
+.support-desk-choice,
+.support-desk-card,
+.support-desk-notice,
+.support-desk-form__input,
+.support-desk-button { box-sizing: border-box; }
+
+/* --- Doors ------------------------------------------------------------------ */
+
+.support-desk-door {
+  display: flex;
+  gap: 0.85rem;
+  align-items: center;
+  margin: 0.5rem 1.25rem;
+  padding: 0.85rem 1rem;
+  border: 1px dashed var(--support-desk-border);
+  border-radius: var(--support-desk-radius);
+  text-decoration: none;
+  color: inherit;
+}
+.support-desk-door:hover { background: var(--support-desk-surface); }
+.support-desk-door__icon {
+  flex: none;
+  width: 2.25rem;
+  height: 2.25rem;
+  display: grid;
+  place-items: center;
+  border-radius: 50%;
+  background: var(--support-desk-surface);
+  font-size: 1.1rem;
+}
+.support-desk-door__body { display: flex; flex-direction: column; gap: 0.1rem; min-width: 0; }
+.support-desk-door__title { font-weight: 650; }
+.support-desk-door__hint { font-size: 0.85rem; color: var(--support-desk-text-muted); }
+
+.support-desk-inbox-door { padding-bottom: 0; }
+
+/* --- Closed section --------------------------------------------------------- */
+
+.support-desk-closed { margin: 0.5rem 0 2rem; }
+.support-desk-closed__summary {
+  cursor: pointer;
+  padding: 0.75rem 1.25rem;
+  font-size: 0.9rem;
+  color: var(--support-desk-text-muted);
+}
+.support-desk-closed[open] .support-desk-closed__summary { color: var(--support-desk-text); }
+.support-desk-closed__capped {
+  margin: 0 1.25rem 0.5rem;
+  font-size: 0.8rem;
+  color: var(--support-desk-text-muted);
+}
+
+/* --- Wizard ----------------------------------------------------------------- */
+
+.support-desk-wizard__header { padding: 1rem 1.25rem 0.25rem; }
+.support-desk-wizard__back {
+  display: inline-block;
+  margin-bottom: 0.5rem;
+  font-size: 0.9rem;
+  color: var(--support-desk-text-muted);
+  text-decoration: none;
+}
+.support-desk-wizard__back::before { content: "‹ "; }
+.support-desk-wizard__ask { font-size: 1.35rem; font-weight: 750; margin: 0 0 0.5rem; }
+
+.support-desk-error {
+  margin: 0 1.25rem 0.75rem;
+  padding: 0.7rem 0.9rem;
+  border-radius: 0.75rem;
+  background: #fef2f2;
+  color: #991b1b;
+  font-size: 0.9rem;
+}
+
+.support-desk-empty { padding: 1.5rem 1.25rem; color: var(--support-desk-text-muted); }
+
+/* --- Choices ---------------------------------------------------------------- */
+
+.support-desk-choices { list-style: none; margin: 0; padding: 0.25rem 0 1rem; }
+
+.support-desk-choice {
+  display: flex;
+  gap: 0.75rem;
+  align-items: center;
+  margin: 0.4rem 1.25rem;
+  padding: 0.9rem 1rem;
+  border: 1px solid var(--support-desk-border);
+  border-radius: var(--support-desk-radius);
+  background: var(--support-desk-card-bg);
+  text-decoration: none;
+  color: inherit;
+}
+.support-desk-choice:hover { background: var(--support-desk-surface); }
+.support-desk-choice__icon { flex: none; font-size: 1.2rem; }
+.support-desk-choice__label { flex: 1; min-width: 0; font-weight: 600; }
+.support-desk-choice__status {
+  flex: none;
+  font-size: 0.75rem;
+  padding: 0.15rem 0.5rem;
+  border-radius: 999px;
+  background: var(--support-desk-surface);
+  color: var(--support-desk-text-muted);
+}
+.support-desk-choice__chevron { flex: none; color: var(--support-desk-text-muted); }
+.support-desk-choice__hint { flex: none; font-size: 0.8rem; color: var(--support-desk-text-muted); }
+.support-desk-choice--taken { background: var(--support-desk-surface); }
+.support-desk-choice--none { justify-content: center; border-style: dashed; font-weight: 500; }
+
+/* --- Context card ----------------------------------------------------------- */
+
+.support-desk-card {
+  display: flex;
+  gap: 0.6rem;
+  align-items: center;
+  margin: 0 1.25rem 0.75rem;
+  padding: 0.8rem 1rem;
+  border-radius: var(--support-desk-radius);
+  background: var(--support-desk-surface);
+}
+.support-desk-card__label { flex: 1; min-width: 0; font-weight: 600; }
+.support-desk-card__status {
+  font-size: 0.75rem;
+  padding: 0.15rem 0.5rem;
+  border-radius: 999px;
+  background: var(--support-desk-card-bg);
+  color: var(--support-desk-text-muted);
+}
+
+/* --- Composer --------------------------------------------------------------- */
+
+.support-desk-form { display: flex; flex-direction: column; gap: 0.75rem; padding: 0 1.25rem 2rem; }
+.support-desk-form__input {
+  width: 100%;
+  padding: 0.85rem 1rem;
+  border: 1px solid var(--support-desk-border);
+  border-radius: var(--support-desk-radius);
+  background: var(--support-desk-card-bg);
+  font: inherit;
+  resize: vertical;
+}
+.support-desk-form__attach { font-size: 0.9rem; color: var(--support-desk-text-muted); }
+.support-desk-form__promise { margin: 0; font-size: 0.85rem; color: var(--support-desk-text-muted); }
+
+.support-desk-button {
+  display: inline-block;
+  align-self: flex-start;
+  padding: 0.75rem 1.4rem;
+  border: 0;
+  border-radius: 999px;
+  background: var(--support-desk-accent);
+  color: var(--support-desk-accent-contrast);
+  font: inherit;
+  font-weight: 650;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+/* --- Notices ---------------------------------------------------------------- */
+
+.support-desk-notice {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  align-items: flex-start;
+  margin: 0 1.25rem 1.5rem;
+  padding: 1rem;
+  border-radius: var(--support-desk-radius);
+  background: var(--support-desk-surface);
+}
+.support-desk-notice__title { margin: 0 1.25rem 0.75rem; font-weight: 600; }
+.support-desk-notice .support-desk-notice__title { margin: 0; }
+
+/* --- Dark ------------------------------------------------------------------- *
+ *
+ * Only the surfaces this file hardcodes: everything else already comes from
+ * a token that chats' own dark handling moves. A host with its own dark
+ * palette overrides the variables and never reaches this block.
+ */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --support-desk-surface: var(--chats-surface, #1f2430);
+    --support-desk-border: var(--chats-border, rgba(255, 255, 255, 0.12));
+    --support-desk-text: var(--chats-text, #f3f4f6);
+    --support-desk-text-muted: var(--chats-text-muted, #9ca3af);
+    --support-desk-card-bg: #111827;
+  }
+
+  /* The cards, the composer and the status pills all read --card-bg above;
+     only the error notice carries colours of its own. */
+  .support-desk-error { background: #3f1d1d; color: #fecaca; }
+}

data/app/controllers/support_desk/application_controller.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # Base controller for every requester-facing screen. It inherits from the
+  # HOST's controller (`config.parent_controller`, "::ApplicationController"
+  # by default) so the host's layout, helpers, authentication, locale
+  # switching and exception handling all apply to the support screens for
+  # free — the same integration style as chats.
+  #
+  # NOTE: the superclass is resolved when this class is autoloaded, which in
+  # a booted app happens AFTER initializers — so `config.parent_controller`
+  # set in config/initializers/support_desk.rb is honoured. In development
+  # the class is reloaded on every change, picking up config changes too.
+  class ApplicationController < SupportDesk.config.parent_controller.constantize
+    before_action :support_desk_authenticate!
+    before_action :ensure_requester!
+    before_action :set_support_desk_current
+
+    helper SupportDesk::EngineHelper
+    helper_method :current_requester
+
+    private
+
+    # The person asking for help, via the host-configured method
+    # (`current_user` by default — Devise-compatible out of the box).
+    def current_requester
+      return @current_requester if defined?(@current_requester)
+
+      method_name = SupportDesk.config.current_requester_method
+      unless respond_to?(method_name, true)
+        raise SupportDesk::ConfigurationError,
+              "support_desk can't find ##{method_name} on #{self.class.superclass.name}. " \
+              "Set config.current_requester_method in config/initializers/support_desk.rb " \
+              "to the controller method that returns the logged-in #{SupportDesk.config.requester_class}."
+      end
+
+      @current_requester = send(method_name)
+    end
+
+    # The host's own authentication filter, so a logged-out visitor meets the
+    # host's login flow and never this gem's idea of one.
+    def support_desk_authenticate!
+      method_name = SupportDesk.config.authenticate_method
+      unless respond_to?(method_name, true)
+        raise SupportDesk::ConfigurationError,
+              "support_desk can't find ##{method_name} on #{self.class.superclass.name}. " \
+              "Set config.authenticate_method in config/initializers/support_desk.rb " \
+              "to your authentication filter (e.g. :authenticate_user! with Devise)."
+      end
+
+      send(method_name)
+    end
+
+    # A host whose authentication filter lets anonymous requests through gets
+    # a 401 rather than a NoMethodError three frames deeper; a host whose
+    # current_requester_method returns the wrong model gets the fix in the
+    # message, because that is a configuration mistake, not a request one.
+    def ensure_requester!
+      return head :unauthorized if current_requester.nil?
+      return if current_requester.respond_to?(:ask_support!)
+
+      raise SupportDesk::ConfigurationError,
+            "config.current_requester_method (##{SupportDesk.config.current_requester_method}) returned a " \
+            "#{current_requester.class}, which doesn't declare `has_support_tickets`. " \
+            "Point it at your #{SupportDesk.config.requester_class}, or add the macro to #{current_requester.class}."
+    end
+
+    # Every transition takes `by:`; this is what it falls back to, so a
+    # requester's own actions are attributed to them without the views
+    # passing an actor around.
+    def set_support_desk_current
+      SupportDesk::Current.actor = current_requester
+      SupportDesk::Current.request = request
+    end
+
+    # Engine URL helpers for chats, from a controller. The mounted proxy
+    # carries the host's mount prefix ("/messages"); the engine's own
+    # url_helpers are the prefix-less fallback for a host that hasn't
+    # mounted chats under its default name.
+    def chats_routes
+      respond_to?(:chats) ? chats : Chats::Engine.routes.url_helpers
+    end
+
+    # Where a case is read and answered: its chats conversation, never a
+    # second thread UI of our own.
+    def conversation_path_for(ticket)
+      return root_path if ticket.conversation.nil?
+
+      chats_routes.conversation_path(ticket.conversation)
+    end
+  end
+end

data/app/controllers/support_desk/console/application_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  module Console
+    # Base controller for the turnkey console. It inherits from the HOST's
+    # controller (`config.console_parent_controller`, "::ApplicationController"
+    # by default), so the host's layout, helpers, authentication filters,
+    # locale switching and exception handling all apply to the console
+    # screens — the same integration style as the requester engine.
+    #
+    # NOTE: the superclass is resolved when this class is autoloaded, which in
+    # a booted app happens AFTER initializers — so a
+    # `config.console_parent_controller` set in config/initializers is
+    # honoured. In development the class reloads with the rest of the app.
+    class ApplicationController < SupportDesk.config.console_parent_controller.constantize
+    end
+  end
+end

data/app/controllers/support_desk/console/tickets_controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  module Console
+    # The whole turnkey console, and proof the public API is enough: the
+    # queue, one case, and the verbs — all of it from the same two concerns
+    # a host includes in their own controller, with nothing private.
+    #
+    # `rails g support_desk:console madmin` writes a controller that reads
+    # exactly like this one into the host app, and copies these views next to
+    # it. If you find yourself wanting something this controller can't do,
+    # that is a gap in Layer 1 or Layer 2 — not a reason to reach in here.
+    class TicketsController < ApplicationController
+      include SupportDesk::Console
+      include SupportDesk::Console::Index
+
+      # One case: the context card, the transcript, the timeline, and exactly
+      # the buttons `actions_for` says this agent may press. `@ticket` is set
+      # by the concern, scoped to the desks this agent may work.
+      def show
+        @context_card = @ticket.context_card
+        @actions = @ticket.actions_for(current_agent)
+      end
+    end
+  end
+end

data/app/controllers/support_desk/tickets_controller.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # The four screens a person who needs help ever sees: their open cases, the
+  # three-step wizard that opens a new one, and the door into the
+  # conversation behind a case.
+  #
+  # The step machine is SupportDesk::Wizard, not this controller: a host that
+  # ejects the views, a native app or a JSON API all drive the same steps, so
+  # nothing here decides anything the wizard could decide.
+  class TicketsController < ApplicationController
+    # How many closed cases the collapsed section lists. Support histories
+    # only grow, and nobody scrolls a year of them on a phone.
+    CLOSED_TICKETS_SHOWN = 20
+
+    before_action :set_wizard, only: %i[new create]
+
+    # Their cases: open ones as rows, closed ones folded away, and the door
+    # to open another.
+    def index
+      tickets = current_requester.support_tickets.includes(:desk, :subject, conversation: { last_message: :sender })
+      @open_tickets = tickets.not_closed.recent_activity_first.to_a
+      @closed_tickets = tickets.closed.newest_first.limit(CLOSED_TICKETS_SHOWN).to_a
+      @closed_count = tickets.closed.count
+      @unread_counts = unread_counts_for(@open_tickets + @closed_tickets)
+    end
+
+    # The wizard. One URL, three frames — which one renders is the wizard's
+    # answer, never a param we trust.
+    def new
+      render :new
+    end
+
+    # Open the case and hand the requester straight to the conversation.
+    #
+    # Two submits land in the same TICKET, because `Ticket.open!` treats a
+    # unique-index collision as "you already opened this one" — but they
+    # post two opening messages into it, so the form also disables its own
+    # button for the length of the submit (`turbo_submits_with`).
+    def create
+      if message.blank? && files.empty?
+        @error = t("support_desk.wizard.message_required")
+        return render :new, status: :unprocessable_entity
+      end
+
+      ticket = @wizard.open!(message, files: files)
+      redirect_to conversation_path_for(ticket)
+    rescue SupportDesk::RateLimited, SupportDesk::TooManyOpenTickets => e
+      render_limit_wall(e)
+    rescue SupportDesk::InvalidTransition
+      # The form was submitted from a step that isn't the composer (a stale
+      # tab, a hand-rolled POST): re-render the step they are actually on.
+      render :new, status: :unprocessable_entity
+    rescue SupportDesk::NotAllowed, SupportDesk::NotSupportable
+      # The subject passed the wizard's check and failed the model's. Same
+      # answer as a forged token: 404.
+      raise ActiveRecord::RecordNotFound
+    end
+
+    # A stable URL for a case — what an email or a push notification links
+    # to. The case is READ in its conversation, so this is a redirect and
+    # nothing else.
+    def show
+      redirect_to conversation_path_for(find_ticket)
+    end
+
+    private
+
+    def set_wizard
+      @wizard = SupportDesk::Wizard.new(current_requester, params)
+      # A token that is forged, expired, or points at somebody else's record
+      # is a 404, never a 403 with a hint: "not yours" and "not there" must
+      # look the same from outside.
+      raise ActiveRecord::RecordNotFound if @wizard.subject_rejected?
+    end
+
+    # By id, or by the reference people read down a phone line ("T-AB12CD").
+    # Always through the requester's OWN tickets, so somebody else's case is
+    # a 404 rather than a redirect into a conversation they can't read.
+    def find_ticket
+      scope = current_requester.support_tickets
+      reference = SupportDesk::Ticket.normalize_reference(params[:id])
+
+      if params[:id].to_s.upcase.start_with?(SupportDesk::Ticket::REFERENCE_PREFIX)
+        scope.find_by!(reference: reference)
+      else
+        scope.find(params[:id])
+      end
+    end
+
+    def message
+      params[:message].to_s
+    end
+
+    def files
+      Array(params[:files]).reject(&:blank?)
+    end
+
+    # "Ya tienes N conversaciones abiertas" — a wall with the way out on it
+    # (their open cases), never a 500 and never a silent failure.
+    def render_limit_wall(error)
+      @limit_reason = error.is_a?(SupportDesk::TooManyOpenTickets) ? "too_many_open" : "too_fast"
+      @open_tickets = current_requester.support_tickets.not_closed
+                                       .includes(:desk, :subject, conversation: { last_message: :sender })
+                                       .recent_activity_first.to_a
+      @unread_counts = unread_counts_for(@open_tickets)
+      render :rate_limited, status: :too_many_requests
+    end
+
+    # One grouped query for every row's badge (see
+    # Chats::Conversation.unread_counts_for).
+    def unread_counts_for(tickets)
+      ids = tickets.filter_map(&:conversation_id)
+      return {} if ids.empty?
+
+      Chats::Conversation.unread_counts_for(current_requester, ids)
+    end
+  end
+end