support_desk 0.1.0

data/lib/generators/support_desk/templates/create_support_desk_tables.rb.erb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+class CreateSupportDeskTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    # ---------------------------------------------------------------------------
+    # support_desk_desks
+    #
+    # Who answers. A desk IS a chats messager (headless: no notifications of
+    # its own, not blockable, grouped inbox row), so its rows are tiny — the
+    # name, avatar and email live in your initializer; `settings` is the
+    # runtime override for hosts that let staff rename a desk from a console.
+    # ---------------------------------------------------------------------------
+    create_table :support_desk_desks, id: primary_key_type do |t|
+      t.string :key, null: false
+      t.send(json_column_type, :settings, default: json_column_default)
+
+      t.timestamps
+    end
+
+    add_index :support_desk_desks, :key, unique: true, name: "index_support_desk_desks_on_key"
+
+    # ---------------------------------------------------------------------------
+    # support_desk_tickets
+    #
+    # A case. One ticket ⇔ one chats conversation: `conversation_id` is
+    # always set (by Ticket.open!, inside the same transaction as the row),
+    # which is why the column is nullable — the conversation is *about* the
+    # ticket, so the ticket has to exist first. `SupportDesk.doctor` checks
+    # that no ticket is ever left without one.
+    #
+    # The denormalized columns are all answers to "what does the queue need
+    # without a join?": awaiting (who owes the next word), waiting_since
+    # (how long), assignee (who holds it), and the SLA clocks.
+    # ---------------------------------------------------------------------------
+    create_table :support_desk_tickets, id: primary_key_type do |t|
+      t.references :desk, null: false, type: foreign_key_type,
+                          foreign_key: { to_table: :support_desk_desks }, index: false
+
+      t.references :requester, polymorphic: true, null: false, type: foreign_key_type, index: false
+      t.string :requester_role
+      t.references :subject, polymorphic: true, null: true, type: foreign_key_type, index: false
+      t.references :assignee, polymorphic: true, null: true, type: foreign_key_type, index: false
+      t.references :closed_by, polymorphic: true, null: true, type: foreign_key_type, index: false
+
+      # The topic path ("payments/withdrawal"), stable across tree edits.
+      t.string :topic, null: false
+      # Set by email (the mail subject) and by the API; never by the wizard.
+      t.string :title
+      # "T-AB12CD" — Crockford base32, for email subjects and phone calls.
+      t.string :reference, null: false
+
+      t.string :status, null: false, default: "open"
+      t.string :awaiting, null: false, default: "agent"
+      t.integer :priority, null: false, default: 0
+      t.string :opened_via, null: false, default: "in_app"
+
+      t.column :conversation_id, foreign_key_type
+      # The message id #register! last folded in — what makes a redelivered
+      # chats event idempotent instead of double-counting an SLA clock.
+      t.column :last_registered_message_id, foreign_key_type
+
+      t.datetime :opened_at, null: false
+      t.datetime :first_agent_reply_at
+      t.datetime :last_requester_message_at
+      t.datetime :last_agent_message_at
+      # Maintained by the model (NOT a generated column): the same
+      # expression has to work on SQLite and MySQL, and a plain column is
+      # one indexable answer on every adapter.
+      t.datetime :waiting_since
+      t.datetime :snoozed_until
+      t.datetime :closed_at
+
+      t.integer :reopen_count, null: false, default: 0
+      t.string :external_ref
+      # What "one open ticket about this" means for this row: the subject,
+      # the topic, or a unique value when the supportable allows several.
+      t.string :cardinality_key, null: false
+      t.send(json_column_type, :metadata, default: json_column_default)
+
+      t.timestamps
+    end
+
+    add_index :support_desk_tickets, :reference, unique: true, name: "index_support_desk_tickets_on_reference"
+    add_index :support_desk_tickets, [ :requester_type, :requester_id, :status ],
+              name: "index_support_desk_tickets_on_requester"
+    add_index :support_desk_tickets, [ :desk_id, :status, :awaiting, :waiting_since ],
+              name: "index_support_desk_tickets_on_queue"
+    add_index :support_desk_tickets, [ :assignee_type, :assignee_id, :status ],
+              name: "index_support_desk_tickets_on_assignee"
+    add_index :support_desk_tickets, [ :subject_type, :subject_id ],
+              name: "index_support_desk_tickets_on_subject"
+    add_index :support_desk_tickets, :conversation_id, unique: true,
+              name: "index_support_desk_tickets_on_conversation_id"
+    add_index :support_desk_tickets, [ :desk_id, :external_ref ], unique: true,
+              name: "index_support_desk_tickets_on_external_ref"
+
+    # THE cardinality guarantee: one open ticket per requester per thing.
+    # A partial unique index is what makes concurrent opens race-safe
+    # without advisory locks — the second INSERT loses and Ticket.open!
+    # hands back the first one's ticket.
+    #
+    # PostgreSQL AND SQLite both support partial indexes, so both get real
+    # enforcement. MySQL doesn't, so there the model's find-then-create is
+    # the whole story and this is a plain lookup index: a host on MySQL that
+    # cares about the race should serialize opens itself.
+    if partial_indexes?
+      add_index :support_desk_tickets, [ :requester_type, :requester_id, :desk_id, :cardinality_key ],
+                unique: true, where: "status <> 'closed'",
+                name: "index_support_desk_tickets_on_open_cardinality"
+    else
+      add_index :support_desk_tickets, [ :requester_type, :requester_id, :desk_id, :cardinality_key ],
+                name: "index_support_desk_tickets_on_open_cardinality"
+    end
+
+    # ---------------------------------------------------------------------------
+    # support_desk_assignments
+    #
+    # Who held the ticket, when, and why they stopped. Assignment is a
+    # history, not a column: hand-offs, drop-in take-overs, shift releases
+    # and "time per agent" are unanswerable from a single assignee_id.
+    # ---------------------------------------------------------------------------
+    create_table :support_desk_assignments, id: primary_key_type do |t|
+      t.references :ticket, null: false, type: foreign_key_type,
+                            foreign_key: { to_table: :support_desk_tickets }, index: false
+      t.references :agent, polymorphic: true, null: false, type: foreign_key_type, index: false
+      t.references :assigned_by, polymorphic: true, null: true, type: foreign_key_type, index: false
+
+      t.string :reason, null: false
+      t.text :note
+      t.datetime :assigned_at, null: false
+      t.datetime :released_at
+      t.string :release_reason
+
+      t.timestamps
+    end
+
+    add_index :support_desk_assignments, [ :ticket_id, :assigned_at ],
+              name: "index_support_desk_assignments_on_ticket"
+    add_index :support_desk_assignments, [ :agent_type, :agent_id, :released_at ],
+              name: "index_support_desk_assignments_on_agent"
+
+    # At most one open assignment per ticket — the invariant behind
+    # `ticket.assignee`. Same story: enforced everywhere partial indexes
+    # exist, checked by `SupportDesk.doctor` everywhere else.
+    if partial_indexes?
+      add_index :support_desk_assignments, :ticket_id, unique: true, where: "released_at IS NULL",
+                name: "index_support_desk_assignments_on_open_ticket"
+    end
+
+    # ---------------------------------------------------------------------------
+    # support_desk_events
+    #
+    # Append-only: everything that happened to a case and wasn't a message.
+    # No updated_at, because there is no update path — the model is readonly
+    # once written. Internal notes are events (kind "note"), never messages,
+    # so they are searchable and in the timeline but never in the
+    # conversation and never mirrored to any channel.
+    # ---------------------------------------------------------------------------
+    create_table :support_desk_events, id: primary_key_type do |t|
+      t.references :ticket, null: false, type: foreign_key_type,
+                            foreign_key: { to_table: :support_desk_tickets }, index: false
+      t.references :actor, polymorphic: true, null: true, type: foreign_key_type, index: false
+
+      t.string :kind, null: false
+      t.send(json_column_type, :payload, default: json_column_default)
+
+      t.datetime :created_at, null: false
+    end
+
+    add_index :support_desk_events, [ :ticket_id, :created_at ], name: "index_support_desk_events_on_ticket"
+    add_index :support_desk_events, [ :ticket_id, :kind ], name: "index_support_desk_events_on_kind"
+
+    # NOTE: value-list vocabularies (status, awaiting, kind, reason) are
+    # validated in the MODELS (frozen constants + inclusion validations),
+    # NOT by DB check constraints — so the gem can grow its taxonomy without
+    # shipping a migration to widen a CHECK.
+  end
+
+  private
+
+  # Honor the host's configured primary key type (uuid vs bigint). Reads the
+  # same setting `rails g model` uses, so an app generated with
+  # `config.generators { |g| g.orm :active_record, primary_key_type: :uuid }`
+  # gets uuid support_desk tables and uuid foreign keys, automatically.
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [ primary_key_type, foreign_key_type ]
+  end
+
+  # Whether this adapter can enforce a rule over SOME rows ("one open ticket
+  # per thing", "one open assignment per ticket"). Everything but MySQL can.
+  #
+  # Trilogy is MySQL, and Rails reports its ADAPTER_NAME as "Trilogy", which a
+  # /mysql/ pattern misses — such a host would be handed a partial unique
+  # index MySQL cannot create and the install would die on it. api_keys hit
+  # this first; see its create_api_keys_table template.
+  def partial_indexes?
+    !connection.adapter_name.match?(/mysql|trilogy/i)
+  end
+
+  # jsonb on every PostgreSQL adapter — matched by prefix because PostGIS
+  # (activerecord-postgis-adapter) answers "PostGIS", not "PostgreSQL", and
+  # an `include?("postgresql")` check silently sent such hosts down the plain
+  # json path. Surfaced while integrating with a PostGIS host.
+  def json_column_type
+    return :jsonb if connection.adapter_name.match?(/\Apostg/i)
+
+    :json
+  end
+
+  # MySQL 8+ doesn't allow default values on JSON columns. Trilogy is MySQL
+  # under a different ADAPTER_NAME, so match both or a Trilogy host is handed
+  # a default MySQL rejects.
+  def json_column_default
+    return nil if connection.adapter_name.match?(/mysql|trilogy/i)
+
+    {}
+  end
+end

data/lib/generators/support_desk/templates/initializer.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+SupportDesk.configure do |config|
+  # ==========================================================================
+  # WHO ASKS, WHO ANSWERS
+  # ==========================================================================
+  #
+  # The model that asks for help — the one with `has_support_tickets`. It
+  # must also be a chats messager (`acts_as_messager`): a requester holds a
+  # seat in the conversation behind every one of their tickets.
+  #
+  # Default: "User"
+  config.requester_class = "User"
+
+  # The agent pool: who gets notified while a ticket is unassigned, who
+  # appears in the "assign to" picker, and who routing may choose. A block
+  # (or a lambda) returning a relation — it's called when it's needed, so it
+  # always reflects today's staff.
+  #
+  # config.agents { User.where(admin: true) }
+
+  # ==========================================================================
+  # CONTROLLER INTEGRATION
+  # ==========================================================================
+  #
+  # The requester-facing engine inherits from your controller, so your
+  # layout, helpers, auth and locale apply to the support screens
+  # automatically.
+  #
+  # config.parent_controller = "::ApplicationController"
+  #
+  # The console (the optional ConsoleEngine and the generated console)
+  # inherits from your admin framework's base controller instead.
+  #
+  # config.console_parent_controller = "::Madmin::ApplicationController"
+  #
+  # How the engine finds the person asking, and the console the person
+  # answering. The defaults work with Devise out of the box.
+  #
+  # config.current_requester_method = :current_user
+  # config.current_agent_method = :current_user
+  #
+  # Your own authentication filter, run before every requester-facing
+  # screen, so a logged-out visitor meets YOUR login flow.
+  #
+  # config.authenticate_method = :authenticate_user!
+
+  # ==========================================================================
+  # THE DESK
+  # ==========================================================================
+  #
+  # What requesters see as the counterpart in their inbox.
+  #
+  # config.name = "Soporte"
+  #
+  # An asset path, a URL, or ->(desk) { … }. Anything image_tag accepts.
+  #
+  # config.avatar = "support-avatar.png"
+  #
+  # The address the email channel answers from (support_desk 0.2).
+  #
+  # config.email = "soporte@example.com"
+
+  # ==========================================================================
+  # TOPICS — what a ticket can be about
+  # ==========================================================================
+  #
+  # A tree, defined here, stored on the ticket as a stable path
+  # ("payments/withdrawal"). Topics carry behaviour — which records they
+  # attach, which picker, which routing, which prefill — which is why they
+  # live in code rather than in a database table somebody edits at 3am.
+  #
+  # Labels come from i18n (support_desk.topics.<path>.label) unless you pass
+  # `label:`. `other` is the free-form leaf; a taxonomy without an exit is
+  # how people pick the wrong topic, so the gem warns at boot when it's
+  # missing.
+  #
+  # config.topics do
+  #   topic :ride, about: Ride
+  #   topic :payments do
+  #     topic :withdrawal, about: Payouts::Withdrawal
+  #     topic :invoice, desk: :billing
+  #   end
+  #   topic :account, only: ->(user) { user.onboarded? }
+  #   topic :safety, priority: :urgent
+  #   other
+  # end
+
+  # ==========================================================================
+  # BEHAVIOUR
+  # ==========================================================================
+  #
+  # Who may answer a ticket somebody else holds:
+  #   :anyone         the reply posts, signed by the drop-in; an unheld
+  #                   ticket is taken by whoever answers first (small teams)
+  #   :take_over      replying reassigns the ticket to the replier (shifts)
+  #   :assignee_only  raises; the console offers "Tomar" instead (regulated)
+  #
+  # config.reply_policy = :anyone
+  #
+  # Whether the requester is told who picked up their ticket:
+  #   :first_only  the first human to take it ("Lucía se ocupa de tu consulta")
+  #   :always      hand-offs too
+  #   :never
+  #
+  # config.announce_assignments = :first_only
+  #
+  # What a requester writing into a closed ticket does:
+  #   :reopen_on_reply  the case comes back (no wall, no dead end)
+  #   :locked           the composer is replaced by a notice
+  #
+  # config.closed_tickets = :reopen_on_reply
+  #
+  # The answer promise: the SLA breach threshold AND the line requesters are
+  # shown when they write ("normalmente en menos de 24 h"). One setting, one
+  # truth. `at_risk_after` is the earlier, softer warning for the queue.
+  #
+  # config.reply_within = 24.hours
+  # config.at_risk_after = 4.hours
+  #
+  # Abuse limits, per requester. Both are walls against one person
+  # hammering the button, and both are checked before the insert rather
+  # than under a lock — so two requests racing about two different things
+  # can leave somebody one ticket over the cap. That is deliberate: the
+  # alternative locks your own users table on every support ticket, and
+  # nobody is harmed by a sixth open case.
+  #
+  # config.open_rate_limit = { to: 5, within: 1.hour }
+  # config.max_open_tickets = 5
+  #
+  # Whether the desk shows in the requester's inbox before they've written:
+  # :always (a "¿Necesitas ayuda?" door), :when_tickets, or :never.
+  #
+  # config.inbox_entry = :always
+  #
+  # How new tickets find an agent. 0.1 ships :manual (unassigned, the pool
+  # is notified, the first take wins) and ->(ticket) { agent } procs.
+  #
+  # config.routing = :manual
+  #
+  # The email channel's two settings, ahead of support_desk 0.2: whether an
+  # agent's reply is also emailed to the requester, and whether a case that
+  # has been waiting on the requester closes itself.
+  #
+  # config.mirror_replies_by_email = :when_away   # :always | :when_away | :never
+  # config.auto_close_after = nil                 # e.g. 7.days
+
+  # ==========================================================================
+  # MORE THAN ONE DESK
+  # ==========================================================================
+  #
+  # Everything above configures the :default desk. Other desks inherit from
+  # it and override what they need.
+  #
+  # config.desk :billing do |desk|
+  #   desk.name = "Facturación"
+  #   desk.reply_within = 8.hours
+  #   desk.agents { User.where(finance: true) }
+  # end
+
+  # ==========================================================================
+  # EVENTS — the gem emits, your app delivers
+  # ==========================================================================
+  #
+  # Multi-subscriber and error-isolated: a subscriber that raises is
+  # reported and the next one still runs. All of them fire after the
+  # transition has committed.
+  #
+  # config.on(:ticket_opened) do |ticket|
+  #   TicketActivityNotifier.with(ticket: ticket).deliver(ticket.agents_to_notify)
+  # end
+  #
+  # config.on(:requester_replied) do |ticket, message|
+  #   TicketActivityNotifier.with(ticket: ticket, record: message).deliver(ticket.agents_to_notify)
+  # end
+  #
+  # The umbrella event every transition also emits — the audit mirror hook.
+  #
+  # config.on(:ticket_transitioned) do |ticket, kind, by:, request:, payload:|
+  #   AuditLog.log("support_ticket_#{kind}", actor: by, request: request, subject: ticket, **payload)
+  # end
+  #
+  # Keep notification TITLES generic (ticket.notification_title does) and put
+  # the detail in the body: a lock screen shouldn't spell out what somebody's
+  # support case is about.
+end

data/lib/generators/support_desk/views_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module SupportDesk
+  module Generators
+    # `rails generate support_desk:views` — eject the requester-facing
+    # templates into the HOST app so they can be restyled. This is the Devise
+    # move (`rails g devise:views`), and it works for the same boring Rails
+    # reason: the host app's `app/views` sits AHEAD of any engine's view paths
+    # in the lookup chain, so a file copied to e.g.
+    # `app/views/support_desk/tickets/index.html.erb` SHADOWS the gem's
+    # bundled default automatically — no config, no registration. Delete your
+    # copy and the gem's default comes back. Upgrade the gem and your ejected
+    # copies are untouched (re-run only if you WANT the new defaults).
+    #
+    # `source_root` points at the engine's own `app/views`, so `directory`
+    # copies the exact templates the engine renders.
+    class ViewsGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../app/views", __dir__)
+
+      desc "Copy support_desk's requester-facing views into your app so you can restyle them."
+
+      # Which groups to eject. `tickets` is every requester screen (the list,
+      # the wizard's three frames, the rows and the doors); `slots` is the
+      # row this engine contributes to chats' inbox.
+      class_option :views,
+                   type: :array,
+                   default: %w[tickets slots],
+                   desc: "Which view groups to copy (tickets, slots)"
+
+      def copy_views
+        directory "support_desk/tickets", "app/views/support_desk/tickets" if include?("tickets")
+        directory "chats/slots", "app/views/chats/slots" if include?("slots")
+      end
+
+      def show_styling_tip
+        say "\n🎨 Views copied. They render with the gem's bundled support_desk.css (and chats.css"
+        say "   for the rows) by default; restyle freely — if your app uses Tailwind, classes you"
+        say "   add here are picked up by your build automatically (the files now live in app/views)."
+      end
+
+      private
+
+      def include?(group)
+        options[:views].map(&:to_s).include?(group)
+      end
+    end
+  end
+end