support_desk 0.1.0

data/config/locales/support_desk.en.yml

@@ -0,0 +1,79 @@
+en:
+  support_desk:
+    system:
+      assigned: "%{agent} is taking care of your request"
+      reassigned: "%{agent} is now taking care of your request"
+    thread:
+      closed_notice: "This conversation is closed. Start a new one if you need anything else."
+      reopened_notice: "We reopened this conversation."
+      promise: "We usually reply in under %{time}"
+    notifications:
+      title: "%{desk} · new message"
+    queue:
+      tabs:
+        awaiting: "Needs a reply"
+        mine: "Mine"
+        unassigned: "Unassigned"
+        open: "Open"
+        snoozed: "Snoozed"
+        closed: "Closed"
+    summary:
+      awaiting_reply: "awaiting reply"
+      awaiting_requester: "awaiting requester"
+      open: "open"
+      closed: "closed"
+    status:
+      open: "Open"
+      snoozed: "Snoozed"
+      closed: "Closed"
+    channels:
+      in_app: "in app"
+      email: "email"
+      intercom: "Intercom"
+      api: "API"
+    tickets:
+      title: "Support"
+      empty_title: "You haven't written to us yet"
+      empty_hint: "Conversations you open will show up here."
+      closed_section:
+        one: "1 closed conversation"
+        other: "%{count} closed conversations"
+      state:
+        awaiting_reply: "We're on it"
+        answered: "We replied"
+        closed: "Closed"
+    doors:
+      new: "Need help?"
+      about: "Need help with %{subject}?"
+      existing: "See your support conversation"
+      new_conversation: "Start a new conversation"
+    inbox:
+      empty_hint: "Need help? Write to us"
+    limits:
+      title: "You already have conversations open"
+      too_many_open_title: "You already have conversations open"
+      too_fast_title: "That was quick"
+      your_message: "What you wrote, so you can copy it:"
+      too_many_open:
+        one: "You already have a conversation open. Write there and we'll keep going in it."
+        other: "You already have %{count} conversations open. Write in one of them and we'll keep going there."
+      too_fast: "You've opened several conversations in a very short time. Give it a moment, or write in one you already have."
+    wizard:
+      ask_topic: "What do you need help with?"
+      ask_subject: "Which one?"
+      write: "Tell us what happened"
+      placeholder: "Tell us what happened"
+      none_of_these: "None of these"
+      already_open: "You already have a conversation open about this"
+      back: "Back"
+      back_to_list: "See your conversations"
+      send: "Send"
+      sending: "Sending"
+      write_anyway: "Write to us anyway"
+      message_required: "Write us a few lines so we can help."
+      nothing_to_pick: "We couldn't find anything to open this conversation about."
+      no_topics: "New conversations can't be opened right now."
+    topics:
+      other:
+        label: "Something else"
+        ask: "What is it about?"

data/config/locales/support_desk.es.yml

@@ -0,0 +1,84 @@
+es:
+  support_desk:
+    # The system message the requester sees when a human picks up their case.
+    system:
+      assigned: "%{agent} se ocupa de tu consulta"
+      reassigned: "%{agent} se ocupa ahora de tu consulta"
+    thread:
+      closed_notice: "Esta conversación está cerrada. Abre una nueva si necesitas algo más."
+      reopened_notice: "Hemos vuelto a abrir esta conversación."
+      promise: "Normalmente respondemos en menos de %{time}"
+    notifications:
+      # Generic on purpose: una pantalla de bloqueo no debe contar de qué va
+      # el caso de nadie. El detalle va en el cuerpo.
+      title: "%{desk} · nuevo mensaje"
+    queue:
+      tabs:
+        awaiting: "Pendientes"
+        mine: "Mi cola"
+        unassigned: "Sin asignar"
+        open: "Abiertos"
+        snoozed: "Pospuestos"
+        closed: "Cerrados"
+    summary:
+      awaiting_reply: "esperando respuesta"
+      awaiting_requester: "esperando al cliente"
+      open: "abierto"
+      closed: "cerrado"
+    status:
+      open: "Abierto"
+      snoozed: "Pospuesto"
+      closed: "Cerrado"
+    channels:
+      in_app: "en la app"
+      email: "correo"
+      intercom: "Intercom"
+      api: "API"
+    # The requester's own list of cases.
+    tickets:
+      title: "Soporte"
+      empty_title: "Todavía no has escrito a soporte"
+      empty_hint: "Cuando abras una conversación la verás aquí."
+      closed_section:
+        one: "1 conversación cerrada"
+        other: "%{count} conversaciones cerradas"
+      state:
+        awaiting_reply: "Estamos con ello"
+        answered: "Te hemos contestado"
+        closed: "Cerrada"
+    # The ways in, from anywhere in the host app.
+    doors:
+      new: "¿Necesitas ayuda?"
+      about: "¿Necesitas ayuda con %{subject}?"
+      existing: "Ver tu conversación de soporte"
+      new_conversation: "Abrir una nueva conversación"
+    inbox:
+      empty_hint: "¿Necesitas ayuda? Escríbenos"
+    limits:
+      title: "Ya tienes conversaciones abiertas"
+      too_many_open_title: "Ya tienes conversaciones abiertas"
+      too_fast_title: "Vas muy rápido"
+      your_message: "Lo que has escrito, para que puedas copiarlo:"
+      too_many_open:
+        one: "Ya tienes una conversación abierta. Escríbenos ahí y seguimos en la misma."
+        other: "Ya tienes %{count} conversaciones abiertas. Escríbenos en una de ellas y seguimos ahí."
+      too_fast: "Has abierto varias conversaciones en muy poco tiempo. Espera un momento o escríbenos en una de las que ya tienes."
+    wizard:
+      ask_topic: "¿Con qué necesitas ayuda?"
+      ask_subject: "¿Sobre cuál?"
+      write: "Cuéntanos qué ha pasado"
+      placeholder: "Cuéntanos qué ha pasado"
+      none_of_these: "Ninguno de estos"
+      already_open: "Ya tienes una conversación abierta"
+      back: "Atrás"
+      back_to_list: "Ver tus conversaciones"
+      send: "Enviar"
+      sending: "Enviando"
+      write_anyway: "Escríbenos de todos modos"
+      message_required: "Escríbenos unas líneas para que podamos ayudarte."
+      nothing_to_pick: "No encontramos nada sobre lo que abrir esta conversación."
+      no_topics: "Ahora mismo no se pueden abrir conversaciones nuevas."
+    topics:
+      other:
+        label: "Otra cosa"
+        ask: "¿De qué se trata?"

data/config/routes.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# The requester-facing engine:
+#
+#   mount SupportDesk::Engine => "/support"
+#
+# Everything a person who needs help touches lives here — the wizard, their
+# list of cases, and the doors into them. The agent console is BYOUI: query
+# objects and presenters (Layer 1), a controller concern and a routing
+# concern (Layer 2), or the generated console (Layer 3). See the README.
+SupportDesk::Engine.routes.draw do
+  # The wizard is ONE url with three frames, so it gets the short spelling:
+  # /support/new, not /support/tickets/new. Every step is a real URL
+  # (`/support/new?topic=payments/withdrawal`), which is what makes the back
+  # gesture, a bookmark and a cold-boot deep link all work.
+  get "new", to: "tickets#new", as: :new_ticket
+
+  # `show` redirects into the chats conversation — a stable URL for a case,
+  # for emails and notifications, that never has to know where chats is
+  # mounted.
+  resources :tickets, only: %i[create show]
+
+  root to: "tickets#index"
+end

data/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/rameerez/support_desk",
+  "public_key": "pk_HibNJE5rTFvy1txHHXUot"
+}

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,34 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 7.2.0"
+
+group :development do
+  gem "appraisal"
+  gem "brakeman", "~> 8.0", require: false
+  gem "rubocop-rails-omakase", require: false
+end
+
+group :test do
+  gem "minitest", "~> 6.0"
+  gem "minitest-mock"
+  gem "simplecov", require: false
+  gem "actioncable"
+  gem "actionmailer"
+  gem "activejob"
+  gem "activestorage"
+  gem "pg"
+  gem "sqlite3"
+  gem "capybara"
+  gem "selenium-webdriver"
+  gem "importmap-rails"
+  gem "propshaft"
+  gem "puma"
+  gem "stimulus-rails"
+  gem "rdoc", ">= 7.0"
+  gem "json", "~> 2.7"
+end
+
+gemspec path: "../"

data/gemfiles/rails_8.0.gemfile

@@ -0,0 +1,34 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 8.0.0"
+
+group :development do
+  gem "appraisal"
+  gem "brakeman", "~> 8.0", require: false
+  gem "rubocop-rails-omakase", require: false
+end
+
+group :test do
+  gem "minitest", "~> 6.0"
+  gem "minitest-mock"
+  gem "simplecov", require: false
+  gem "actioncable"
+  gem "actionmailer"
+  gem "activejob"
+  gem "activestorage"
+  gem "pg"
+  gem "sqlite3"
+  gem "capybara"
+  gem "selenium-webdriver"
+  gem "importmap-rails"
+  gem "propshaft"
+  gem "puma"
+  gem "stimulus-rails"
+  gem "rdoc", ">= 7.0"
+  gem "json", "~> 2.7"
+end
+
+gemspec path: "../"

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,34 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 8.1.0"
+
+group :development do
+  gem "appraisal"
+  gem "brakeman", "~> 8.0", require: false
+  gem "rubocop-rails-omakase", require: false
+end
+
+group :test do
+  gem "minitest", "~> 6.0"
+  gem "minitest-mock"
+  gem "simplecov", require: false
+  gem "actioncable"
+  gem "actionmailer"
+  gem "activejob"
+  gem "activestorage"
+  gem "pg"
+  gem "sqlite3"
+  gem "capybara"
+  gem "selenium-webdriver"
+  gem "importmap-rails"
+  gem "propshaft"
+  gem "puma"
+  gem "stimulus-rails"
+  gem "rdoc", ">= 7.0"
+  gem "json", "~> 2.7"
+end
+
+gemspec path: "../"

data/lib/generators/support_desk/console_generator.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module SupportDesk
+  module Generators
+    # `rails generate support_desk:console madmin` — the agent console as
+    # files in YOUR app: a controller that includes the two console
+    # concerns, a madmin resource so the nav and search know tickets exist,
+    # and the whole view set.
+    #
+    # The views are copied straight out of `SupportDesk::ConsoleEngine` —
+    # the same templates the mounted console renders, not a second set that
+    # can drift from it. They reference nothing private: queue tabs come
+    # from `queue.tabs`, rows from the ticket's own predicates, buttons from
+    # `actions_for`, paths from the console concern's
+    # `console_ticket_path` (which reads THIS controller's route, so the
+    # files work under any namespace). Edit them freely.
+    #
+    # Idempotent: existing files are left alone unless you pass `--force`.
+    class ConsoleGenerator < Rails::Generators::Base
+      # Where the ConsoleEngine keeps the views both consoles render. One
+      # source of truth, copied — never a symlink or a second copy to
+      # maintain.
+      VIEWS_ROOT = File.expand_path("../../../app/views/support_desk/console/tickets", __dir__)
+
+      source_root File.expand_path("templates/console", __dir__)
+
+      desc "Generate a support console (controller, admin resource and views) in your app"
+
+      argument :target, type: :string, default: "madmin",
+               desc: "The admin namespace to generate into (madmin)"
+
+      def self.source_paths
+        [ source_root, VIEWS_ROOT ]
+      end
+
+      def copy_controller
+        template "controller.rb.erb", "app/controllers/#{target}/support_tickets_controller.rb", **file_options
+      end
+
+      # Only madmin has a resource concept; other targets get the controller
+      # and the views, and wire their own nav.
+      def copy_admin_resource
+        return unless madmin?
+
+        template "resource.rb.erb", "app/madmin/resources/support_ticket_resource.rb", **file_options
+      end
+
+      def copy_views
+        Dir.children(VIEWS_ROOT).sort.each do |view|
+          copy_file view, "#{views_path}/#{view}", **file_options
+        end
+      end
+
+      def display_post_install_message
+        say "\n🎫 A support console has been generated in app/controllers/#{target}/ and #{views_path}/.", :green
+        say "\nTo finish:"
+
+        say "  1. One route line:"
+        say "       # config/routes.rb"
+        say "       namespace :#{target} do"
+        say "         resources :support_tickets, only: %i[index show], concerns: :support_console"
+        say "       end"
+
+        say "  2. A badge in your admin nav:"
+        say "       <%= render \"#{target}/support_tickets/nav_badge\", agent: current_user %>"
+        say "       # links to #{target}_support_tickets_path"
+
+        say "  3. Check who may open it:"
+        say "       config.current_agent_method = :current_user   # who is answering"
+        say "       config.visible_desks_for    = ->(agent) { … } # which desks they may work"
+        say "       config.authorize_console    = ->(agent, ticket, action) { … }"
+
+        say "\n  The views are Tailwind and all copy comes from your locales, so restyle"
+        say "  and retranslate freely — nothing in the gem reads them back."
+        say "\nYour team has a queue. 🚀\n", :green
+      end
+
+      private
+
+      # The module the generated controller lives in ("madmin" → "Madmin").
+      def module_name = target.camelize
+
+      def views_path = "app/views/#{target}/support_tickets"
+
+      def madmin? = target == "madmin"
+
+      # Idempotent by default: a second run leaves your edits alone. `--force`
+      # (Thor's own flag) is how you take the new defaults after an upgrade.
+      def file_options = options[:force] ? {} : { skip: true }
+    end
+  end
+end

data/lib/generators/support_desk/install_generator.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module SupportDesk
+  module Generators
+    # `rails generate support_desk:install` — copies the adaptive migration
+    # (uuid or bigint keys, adapter-aware JSON columns, PostgreSQL partial
+    # unique indexes) and the annotated initializer, then prints the three
+    # model lines and one route line that finish the install.
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Install support_desk's migration and initializer"
+
+      # Rails' migration numbering, borrowed from ActiveRecord's generators.
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      # The schema: four tables, adaptive keys, partial indexes where the
+      # adapter has them.
+      def create_migration_file
+        migration_template "create_support_desk_tables.rb.erb",
+                           File.join(db_migrate_path, "create_support_desk_tables.rb")
+      end
+
+      # The annotated initializer — every setting the gem has, with what it
+      # means and what it defaults to.
+      def create_initializer
+        template "initializer.rb", "config/initializers/support_desk.rb"
+      end
+
+      # The three model lines and one route line that finish the install.
+      def display_post_install_message
+        say "\n🎫 The `support_desk` gem has been installed.", :green
+        say "\nTo complete the setup:"
+
+        say "  1. Run 'rails db:migrate' to create the support_desk tables."
+        say "     ⚠️  You must run migrations before starting your app!", :yellow
+
+        say "  2. Three model lines — who asks, what they ask about, who answers:"
+        say "       class User < ApplicationRecord"
+        say "         acts_as_messager                  # chats"
+        say "         has_support_tickets"
+        say "         acts_as_support_agent if: :admin?"
+        say "       end"
+        say ""
+        say "       class Ride < ApplicationRecord"
+        say "         supportable topic: :ride"
+        say "       end"
+
+        say "  3. One route line:"
+        say "       # config/routes.rb"
+        say "       mount SupportDesk::Engine => \"/support\""
+
+        say "  4. Tell the desk who it is, in config/initializers/support_desk.rb:"
+        say "       config.name = \"Soporte\""
+        say "       config.agents { User.admin }"
+        say "       config.topics { topic :ride, about: Ride; other }"
+
+        say "\n  Locales: es and en ship with the gem. To translate your topic labels,"
+        say "  add support_desk.topics.<path>.label keys to your own locale files."
+
+        say "\n  The requester's screens render with bundled styles. To restyle them,"
+        say "  'rails g support_desk:views' copies them into your app, where they"
+        say "  shadow the gem's copies (delete yours and the default comes back)."
+
+        say "\n  Email (0.2): when the channel lands, route inbound mail with"
+        say "  # app/mailboxes/application_mailbox.rb"
+        say "  #   routing(/^support@/i => :support_desk)"
+
+        say "\nCheck your work any time with SupportDesk.doctor.print"
+        say "You now have support tickets that are real conversations. 🚀\n", :green
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/generators/support_desk/templates/console/controller.rb.erb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module <%= module_name %>
+  # The support console, yours to edit.
+  #
+  # Everything an agent can do arrives through two concerns:
+  #
+  #   SupportDesk::Console         the verbs — reply, take, assign, hand_off,
+  #                                release, close, reopen, note, change_topic,
+  #                                next — each one finding the ticket inside
+  #                                `config.visible_desks_for`, asking
+  #                                `config.authorize_console`, and turning
+  #                                every refusal into a flash
+  #   SupportDesk::Console::Index  @queue, @scope and @tickets from params
+  #
+  # The routes come from the `:support_console` routing concern:
+  #
+  #   namespace :<%= target %> do
+  #     resources :support_tickets, only: %i[index show], concerns: :support_console
+  #   end
+  #
+  # Both `index` and `show` are yours — the gem deliberately doesn't own the
+  # screens. Everything they need is plain Ruby: `SupportDesk::Queue`,
+  # `ticket.context_card`, `ticket.timeline`, `ticket.actions_for(agent)`.
+  class SupportTicketsController < <%= module_name %>::ApplicationController
+    include SupportDesk::Console
+    include SupportDesk::Console::Index
+
+    # One case. `@ticket` is already set (and already scoped to the desks
+    # this agent may work) by the concern.
+    def show
+      @context_card = @ticket.context_card
+      @actions = @ticket.actions_for(current_agent)
+    end
+
+    private
+
+    # Who is answering. Point this at whatever your admin already uses;
+    # `config.current_agent_method` is the alternative if you'd rather not
+    # write the method at all.
+    def current_agent = current_user
+  end
+end

data/lib/generators/support_desk/templates/console/resource.rb.erb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Tells madmin that support tickets exist: the nav entry, the search index
+# and the record links other resources make when they point at a ticket.
+#
+# The console itself is NOT this resource's index and show — those are
+# <%= module_name %>::SupportTicketsController, which is a real support
+# screen rather than a table of columns. The path overrides below are what
+# send madmin's own links there.
+class SupportTicketResource < Madmin::Resource
+  model SupportDesk::Ticket
+
+  attribute :reference, index: true, form: false
+  attribute :title, index: true, form: false
+  attribute :topic, index: true, form: false
+  attribute :status, index: true, form: false
+  attribute :awaiting, index: true, form: false
+  attribute :requester, :polymorphic, index: true, form: false
+  attribute :assignee, :polymorphic, index: true, form: false
+  attribute :subject, :polymorphic, index: false, form: false
+  attribute :opened_via, index: false, form: false
+  attribute :waiting_since, index: true, form: false
+  attribute :opened_at, index: false, form: false
+  attribute :closed_at, index: false, form: false
+
+  scope :open
+  scope :closed
+  scope :unassigned
+  scope :awaiting_reply
+
+  menu label: "Support"
+
+  # "T-AB12CD · Order SO1" reads better than "Ticket #42" everywhere madmin
+  # prints a record: breadcrumbs, search results, association links.
+  def self.display_name(record) = "#{record.reference} · #{record.label}"
+
+  def self.index_path(options = {}) = url_helpers.<%= target %>_support_tickets_path(options)
+  def self.show_path(record) = url_helpers.<%= target %>_support_ticket_path(record)
+  def self.new_path = index_path
+  def self.edit_path(record) = show_path(record)
+
+  def self.default_sort_column = "waiting_since"
+  def self.default_sort_direction = "asc"
+end