support_desk 0.1.0

data/lib/support_desk/macros.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # The three host-facing macros. The engine extends `ActiveRecord::Base`
+  # with this module, so any model can declare:
+  #
+  #   class User < ApplicationRecord
+  #     acts_as_messager                    # chats
+  #     has_support_tickets                 # can ask for help
+  #     acts_as_support_agent if: :admin?   # can answer
+  #   end
+  #
+  #   class Ride < ApplicationRecord
+  #     supportable topic: :ride            # can be asked about
+  #   end
+  #
+  # Each macro includes the matching concern — all the behaviour lives in
+  # SupportDesk::Requester / Supportable / Agent, so it's discoverable,
+  # testable, and `include`-able directly when a host prefers that style.
+  module Macros
+    # The requester side. `desk:` names which desk this model writes to;
+    # `as:` records a role on every ticket ("driver", "passenger") so the
+    # console can tell two kinds of requester apart.
+    def has_support_tickets(desk: :default, as: nil)
+      include SupportDesk::Requester
+
+      self.support_desk_requester_options = { desk: desk.to_sym, as: as&.to_s }.freeze
+      SupportDesk.register_requester(self)
+    end
+
+    # Makes a domain record something people can ask about: a ride, an
+    # order, a withdrawal. `topic:` is the topic a ticket opened from this
+    # record's door lands on; `candidates:` overrides the "which one?"
+    # picker; `one_open_ticket: false` lets a requester hold several open
+    # tickets about the same record.
+    def supportable(topic:, candidates: nil, one_open_ticket: true)
+      if candidates && !candidates.respond_to?(:call)
+        raise ConfigurationError, "supportable candidates: must respond to #call, got #{candidates.inspect}"
+      end
+
+      include SupportDesk::Supportable
+
+      self.support_desk_supportable_options = {
+        topic: topic.to_s, candidates: candidates, one_open_ticket: !!one_open_ticket
+      }.freeze
+      SupportDesk.register_supportable(self)
+    end
+
+    # The agent side: who may answer. `if:` is the per-record eligibility
+    # check (a Symbol method name or a callable); `kind:` is :human or :ai.
+    # No verbs are added — the ticket is the subject of every sentence
+    # (`ticket.assign!(to: lucia)`), never the agent.
+    def acts_as_support_agent(kind: :human, **options)
+      unknown = options.keys - [ :if ]
+      if unknown.any?
+        raise ConfigurationError,
+              "unknown acts_as_support_agent option#{"s" if unknown.size > 1} " \
+              "#{unknown.map(&:inspect).join(", ")} — known options are :if, :kind"
+      end
+
+      condition = options[:if]
+      unless condition.nil? || condition.is_a?(Symbol) || condition.respond_to?(:call)
+        raise ConfigurationError,
+              "acts_as_support_agent if: must be a method name or a callable, got #{condition.inspect}"
+      end
+
+      include SupportDesk::Agent
+
+      self.support_desk_agent_options = { if: condition, kind: kind.to_sym }.freeze
+      SupportDesk.register_agent(self)
+    end
+  end
+end

data/lib/support_desk/models/application_record.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # Abstract base for every support_desk model. Kept separate from the
+  # host's ApplicationRecord on purpose: the gem's models must not inherit
+  # host callbacks or scopes, and the host must be able to swap its own base
+  # class without touching ours.
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/lib/support_desk/models/assignment.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # Who held a 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`.
+  #
+  # `ticket.assignee` is the denormalised pointer to the one row with
+  # `released_at IS NULL`; the two are written together inside one
+  # transaction, and `SupportDesk.doctor` checks they still agree.
+  class Assignment < ApplicationRecord
+    self.table_name = "support_desk_assignments"
+
+    REASONS = %w[taken assigned handed_off routed drop_in_takeover escalated reopened].freeze
+    RELEASE_REASONS = %w[handed_off released shift_end closed escalated].freeze
+
+    belongs_to :ticket, class_name: "SupportDesk::Ticket", inverse_of: :assignments
+    belongs_to :agent, polymorphic: true
+    belongs_to :assigned_by, polymorphic: true, optional: true
+
+    validates :reason, inclusion: { in: REASONS }
+    validates :release_reason, inclusion: { in: RELEASE_REASONS }, allow_nil: true
+
+    scope :open, -> { where(released_at: nil) }
+    scope :released, -> { where.not(released_at: nil) }
+    scope :chronological, -> { order(:assigned_at, :id) }
+    scope :for_agent, ->(agent) { where(agent: agent) }
+
+    # Hand the ticket to +agent+: closes whoever held it and opens a new
+    # row. The caller holds the ticket's row lock (every transition does),
+    # which is what makes "at most one open assignment" true rather than
+    # hopeful — the partial unique index is the belt underneath it.
+    def self.open!(ticket:, agent:, by: nil, reason: :assigned, note: nil, release_reason: nil)
+      open.where(ticket: ticket).each do |assignment|
+        assignment.release!(reason: release_reason || default_release_reason(reason))
+      end
+
+      create!(
+        ticket: ticket,
+        agent: agent,
+        assigned_by: by.is_a?(Symbol) ? nil : by,
+        reason: reason.to_s,
+        note: note,
+        assigned_at: Time.current
+      )
+    end
+
+    # What the previous holder's row records when a new one opens.
+    def self.default_release_reason(reason)
+      case reason.to_s
+      when "handed_off" then "handed_off"
+      when "escalated" then "escalated"
+      else "released"
+      end
+    end
+
+    # Whether this is the seat somebody is sitting in right now.
+    def open? = released_at.nil?
+    def released? = !open?
+
+    # Close this row. Idempotent: releasing a released assignment changes
+    # nothing.
+    def release!(reason: :released)
+      return self unless open?
+
+      update!(released_at: Time.current, release_reason: reason.to_s)
+      self
+    end
+
+    # How long this agent held the ticket (so far).
+    def held_for
+      return nil if assigned_at.nil?
+
+      ActiveSupport::Duration.build(((released_at || Time.current) - assigned_at).to_i)
+    end
+
+    # The seat, in one line.
+    def inspect
+      "#<SupportDesk::Assignment ticket=#{ticket_id} agent=#{agent_type}##{agent_id} " \
+        "#{reason}#{" released:#{release_reason}" if released?}>"
+    end
+  end
+end

data/lib/support_desk/models/concerns/agent.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # Included by `acts_as_support_agent`. Agents are never chats participants
+  # — the desk sends, the agent *authors* — so a model becomes an agent with
+  # no messaging setup at all.
+  #
+  #   class User < ApplicationRecord
+  #     acts_as_support_agent if: :admin?
+  #   end
+  #
+  #   lucia.support_agent?      # => true
+  #   lucia.support_queue.mine  # => relation
+  module Agent
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :support_desk_agent_options, instance_writer: false,
+                                                   default: { if: nil, kind: :human }.freeze
+
+      has_many :support_assignments,
+               class_name: "SupportDesk::Assignment",
+               as: :agent,
+               inverse_of: :agent,
+               dependent: :nullify
+
+      has_many :support_tickets_assigned,
+               class_name: "SupportDesk::Ticket",
+               as: :assignee,
+               inverse_of: :assignee,
+               dependent: :nullify
+    end
+
+    class_methods do
+      def support_agent_class? = true
+    end
+
+    # Whether this record may answer tickets right now — the `if:` condition
+    # from the macro, honoured.
+    def support_agent?
+      condition = self.class.support_desk_agent_options[:if]
+      return true if condition.nil?
+      return !!public_send(condition) if condition.is_a?(Symbol)
+
+      !!condition.call(self)
+    end
+
+    # :human or :ai. Bots disclose themselves through this (04).
+    def support_agent_kind
+      self.class.support_desk_agent_options[:kind]
+    end
+
+    # The signature requesters see under an answer.
+    def support_agent_name
+      %i[public_name display_name name].each do |method|
+        value = try(method)
+        return value.to_s if value.present?
+      end
+
+      "#{self.class.model_name.human} #{id}"
+    end
+
+    # Anything `image_tag` accepts, or nil.
+    def support_agent_avatar = try(:avatar)
+
+    # Whether the desk should route or notify this agent right now. True by
+    # default: hosts back it with a schedule, a presence bit, or the duty
+    # table that ships in 0.3.
+    def on_duty? = true
+
+    # How many open tickets this agent can hold; nil is unlimited.
+    def support_capacity = nil
+
+    # This agent's view of the desk: tabs, counts, badge, next ticket.
+    def support_queue(desk: nil)
+      SupportDesk::Queue.for(self, desk: desk)
+    end
+  end
+end

data/lib/support_desk/models/concerns/requester.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # Included by `has_support_tickets`. Adds exactly four methods — the whole
+  # requester side of the gem:
+  #
+  #   alice.ask_support!("El viaje no aparece verificado", about: ride)
+  #   alice.support_tickets.open.about(ride)
+  #   alice.awaiting_support_reply?
+  #   alice.unread_support_count
+  module Requester
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :support_desk_requester_options, instance_writer: false,
+                                                       default: { desk: :default, as: nil }.freeze
+
+      has_many :support_tickets,
+               class_name: "SupportDesk::Ticket",
+               as: :requester,
+               inverse_of: :requester,
+               dependent: :restrict_with_error
+    end
+
+    class_methods do
+      def support_desk_key = support_desk_requester_options[:desk]
+    end
+
+    # Open a ticket and say the first thing. Returns the SupportDesk::Ticket
+    # — the existing open one when this requester already has a ticket about
+    # the same record (or, for free-form tickets, the same topic).
+    #
+    #   alice.ask_support!("No me han pagado", about: withdrawal)
+    #   alice.ask_support!("¿Cómo borro mi cuenta?", topic: :account)
+    #
+    # Raises NotSupportable, UnknownTopic, NotAllowed, RateLimited,
+    # TooManyOpenTickets.
+    def ask_support!(message, about: nil, topic: nil, files: [], via: :in_app)
+      key = self.class.support_desk_requester_options[:desk]
+      desk = SupportDesk.desk(key) ||
+             raise(SupportDesk::ConfigurationError,
+                   "#{self.class} writes to desk #{key.inspect}, which isn't configured — " \
+                   "its tickets would silently land on the default desk")
+
+      SupportDesk::Ticket.open!(
+        requester: self,
+        message: message,
+        about: about,
+        topic: topic,
+        files: files,
+        via: via,
+        desk: desk,
+        requester_role: self.class.support_desk_requester_options[:as]
+      )
+    end
+
+    # True when any of this requester's open tickets is waiting on the desk.
+    def awaiting_support_reply?
+      support_tickets.not_closed.awaiting_reply.exists?
+    end
+
+    # Unread messages across every support conversation this requester has,
+    # counted against the chats read horizon — the number for a nav badge.
+    def unread_support_count
+      conversation_ids = support_tickets.where.not(conversation_id: nil).distinct.pluck(:conversation_id)
+      return 0 if conversation_ids.empty?
+
+      Chats::Conversation.unread_counts_for(self, conversation_ids).values.sum
+    end
+  end
+end

data/lib/support_desk/models/concerns/supportable.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # Included by `supportable`. Every method has a working default; override
+  # the ones that matter to you:
+  #
+  #   class Ride < ApplicationRecord
+  #     supportable topic: :ride
+  #
+  #     def support_label  = "#{origin} → #{destination} · #{departs_on.to_fs(:short)}"
+  #     def support_status = status_pill&.label
+  #     def support_context = { "Conductor" => driver.public_name, "Plazas" => seats }
+  #     def support_url    = Rails.application.routes.url_helpers.madmin_ride_path(self)
+  #     def supportable_by?(requester) = participants.exists?(user: requester)
+  #   end
+  module Supportable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :support_desk_supportable_options, instance_writer: false,
+                                                         default: { topic: nil, candidates: nil,
+                                                                    one_open_ticket: true }.freeze
+
+      has_many :support_tickets,
+               class_name: "SupportDesk::Ticket",
+               as: :subject,
+               inverse_of: :subject,
+               dependent: :nullify
+    end
+
+    class_methods do
+      # True — this class is supportable. (The predicate exists on the class
+      # AND the instance so config validation, doors and pickers can ask
+      # either one.)
+      def supportable? = true
+
+      # The records the "which one?" picker offers +requester+: the
+      # `candidates:` proc when given, else the requester's own association
+      # by this model's plural name, else none.
+      def support_candidates_for(requester)
+        proc = support_desk_supportable_options[:candidates]
+        return proc.call(requester) if proc.respond_to?(:call)
+
+        association = model_name.plural
+        return requester.public_send(association) if requester.respond_to?(association)
+
+        none
+      end
+
+      # Whether a requester may hold only one open ticket about a given
+      # record of this class.
+      def one_open_support_ticket? = support_desk_supportable_options[:one_open_ticket]
+    end
+
+    # True — this record can be asked about.
+    def supportable? = true
+
+    # The topic a ticket opened about this record lands on.
+    def support_topic
+      self.class.support_desk_supportable_options[:topic]
+    end
+
+    # How this record is named in ticket labels, context cards and the
+    # opening notice.
+    def support_label
+      "#{self.class.model_name.human} #{id}"
+    end
+
+    # A short status pill rendered under the label, in the picker and the
+    # console. nil renders nothing.
+    def support_status = nil
+
+    # Key/value pairs an agent sees in the console's context card. Rendered
+    # to agents only — you decide what belongs there.
+    def support_context = {}
+
+    # Where an agent can open this record in your admin. nil renders no link.
+    def support_url = nil
+
+    # May +requester+ open a ticket about this record? The default is the
+    # obvious ownership check; override it for anything else.
+    def supportable_by?(requester)
+      return false if requester.nil?
+
+      respond_to?(:user) && user == requester
+    end
+  end
+end

data/lib/support_desk/models/desk.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # The desk: who answers, as far as the requester is concerned.
+  #
+  # A desk is a chats messager — a headless one. It has no notifications of
+  # its own (agents are notified through the host's own fan-out, never by
+  # this gem) and can't be blocked or reported as a person, because it isn't
+  # one. Its conversations collapse into a single grouped inbox row, so
+  # somebody with four open tickets sees "Soporte" once, not four times.
+  #
+  #   SupportDesk.desk            # the :default desk, memoised
+  #   SupportDesk.desk(:billing)  # another one
+  #
+  # Rows are created lazily and never INSERT-first: a desk is read on every
+  # page and written once in its life.
+  class Desk < ApplicationRecord
+    self.table_name = "support_desk_desks"
+
+    acts_as_messager notifications: false,
+                     blockable: false,
+                     inbox: :grouped,
+                     group_path: ->(_viewer) { SupportDesk.root_path }
+
+    has_many :tickets,
+             class_name: "SupportDesk::Ticket",
+             inverse_of: :desk,
+             dependent: :restrict_with_error
+
+    # Ruby-side default so settings is always a Hash even on MySQL, where a
+    # JSON column can't carry a DB default.
+    attribute :settings, default: -> { {} }
+
+    validates :key, presence: true
+
+    # The desk for +key+, found or created. Never INSERT-first: `find_by`
+    # answers from the index on every call but the very first.
+    #
+    # `SupportDesk.desk` then memoises the record FOR THE LIFE OF THE
+    # PROCESS, so a `settings` change written by another process (a console,
+    # another web worker) is not picked up until this one boots again or
+    # somebody calls `SupportDesk.reset_desks!`. That is the trade the
+    # performance requirement asks for — a desk is read on every page and
+    # written once in its life — and it is why configuration, not
+    # `settings`, is the place to put anything that has to change together
+    # everywhere.
+    def self.for(key)
+      key = key.to_s
+      find_by(key: key) || create_or_find_by!(key: key)
+    end
+
+    # This desk's slice of the configuration.
+    def config
+      SupportDesk.config.desk(key)
+    end
+
+    # What requesters see as the counterpart. Configuration wins; the
+    # `settings` column is the runtime fallback for hosts that let staff
+    # rename a desk from a console.
+    def name
+      config.read(:name) || settings["name"].presence || key.to_s.humanize
+    end
+    alias display_name name
+
+    # Anything `image_tag` accepts, or nil. A callable is passed the desk.
+    def avatar
+      value = config.read(:avatar) || settings["avatar"].presence
+      value.respond_to?(:call) ? value.call(self) : value
+    end
+
+    # The address the email channel answers from (0.2).
+    def email
+      config.read(:email) || settings["email"].presence
+    end
+
+    # The agent pool, resolved from `config.agents`.
+    def agents
+      config.agent_pool
+    end
+
+    # The pool, minus anyone who says they're off duty.
+    def on_duty_agents
+      agents.select { |agent| !agent.respond_to?(:on_duty?) || agent.on_duty? }
+    end
+
+    # Whether +record+ may answer this desk's tickets.
+    def agent?(record)
+      return false if record.nil? || record.is_a?(Symbol)
+
+      record.respond_to?(:support_agent?) && record.support_agent?
+    end
+
+    # A desk prints as its name — it's a counterpart, not a row.
+    def to_s = name
+
+    # The desk, in one line.
+    def inspect
+      "#<SupportDesk::Desk #{key} #{name.inspect}>"
+    end
+  end
+end

data/lib/support_desk/models/event.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # The append-only timeline of everything that is not a message: who took
+  # the ticket, who handed it off, who closed it, what an agent noted.
+  #
+  # Rows are written inside the same transaction as the transition they
+  # describe — exactly one row per transition — and are read-only forever
+  # after. Hosts with tamper-evident logs mirror them by subscribing to
+  # `:ticket_transitioned` rather than by writing here.
+  class Event < ApplicationRecord
+    self.table_name = "support_desk_events"
+
+    KINDS = %w[
+      opened assigned handed_off released drop_in closed reopened topic_changed subject_attached note
+      snoozed woken escalated channel_added email_bounced email_unverified rated tagged
+    ].freeze
+
+    belongs_to :ticket, class_name: "SupportDesk::Ticket", inverse_of: :events
+    belongs_to :actor, polymorphic: true, optional: true
+
+    attribute :payload, default: -> { {} }
+
+    validates :kind, inclusion: { in: KINDS }
+
+    scope :chronological, -> { order(:created_at, :id) }
+    scope :of_kind, ->(*kinds) { where(kind: kinds.flatten.map(&:to_s)) }
+    scope :notes, -> { where(kind: "note") }
+    # Everything a requester may see in an export: their own case's story,
+    # never the desk's internal reasoning.
+    scope :requester_visible, -> { where.not(kind: %w[note drop_in]) }
+
+    # Write one event. `actor` may be a record or a Symbol (`:system`,
+    # `:routing`) — symbols are kept in the payload, since there is no row
+    # to point at.
+    def self.record!(ticket:, kind:, actor: nil, payload: {})
+      create!(
+        ticket: ticket,
+        kind: kind.to_s,
+        actor: actor.is_a?(Symbol) || actor.nil? ? nil : actor,
+        payload: payload.merge(actor.is_a?(Symbol) ? { "by" => actor.to_s } : {})
+      )
+    end
+
+    # Append-only, enforced the way ActiveRecord can enforce it: a loaded
+    # event refuses `update!`, `update_column` and friends.
+    #
+    # It is NOT tamper-proofing. `update_all` and `delete_all` never
+    # instantiate a record, so they bypass this exactly as they bypass every
+    # other model-level rule, and anything with database access can rewrite
+    # a row regardless. A host that needs tamper EVIDENCE mirrors
+    # `:ticket_transitioned` into its own hash-chained log; this guarantees
+    # that the gem, and code using the gem's models, only ever appends.
+    def readonly?
+      persisted?
+    end
+
+    # Who acted, as something you can print: the actor record, or the
+    # symbol kept in the payload.
+    def actor_or_system
+      actor || payload["by"]&.to_sym
+    end
+
+    # The text of an internal note, for kind "note".
+    def note = payload["note"]
+
+    # The event, in one line.
+    def inspect
+      "#<SupportDesk::Event #{kind} ticket=#{ticket_id} #{created_at&.iso8601}>"
+    end
+  end
+end