support_desk 0.1.0

data/lib/support_desk/queue.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # An agent's view of a desk: the tabs, the counts, the badge, and what to
+  # work on next. Plain relations all the way down, so any UI — a console, a
+  # rake task, a Slack command — renders from the same object.
+  #
+  #   q = lucia.support_queue
+  #   q.awaiting          # the "needs an answer" tab, as a relation
+  #   q.counts            # { mine: 2, unassigned: 3, … } in ONE query
+  #   q.badge             # the nav number
+  #   q.next              # the ticket to open now
+  #   q.tabs              # [[:awaiting, "Pendientes", 4], …]
+  class Queue
+    # Every tab a queue can answer for, in display order. `scope` and
+    # `counts` both cover all of them.
+    TABS = %i[awaiting mine unassigned open snoozed closed].freeze
+
+    # Tabs whose FEATURE hasn't shipped yet. Snoozing lands in 0.2: until a
+    # ticket can actually be snoozed, the tab is a permanent column of
+    # zeros, and a control that never does anything is how a console starts
+    # teaching people not to read it. The relation and the count stay — a
+    # host importing snoozed tickets from elsewhere can still ask for them
+    # by name — but nothing offers the tab.
+    UNRELEASED_TABS = %i[snoozed].freeze
+
+    # The tabs a console should render, in display order.
+    VISIBLE_TABS = (TABS - UNRELEASED_TABS).freeze
+
+    # How long a nav badge may lie. Long enough that a busy console isn't
+    # counting rows on every request, short enough that nobody notices.
+    BADGE_TTL = 30
+
+    attr_reader :agent, :desk
+
+    # The queue for +agent+ on +desk+ (the default desk when omitted).
+    def self.for(agent, desk: nil)
+      new(agent, desk: desk || SupportDesk.desk)
+    end
+
+    # An agent's view of one desk. Prefer `Queue.for` or
+    # `agent.support_queue`.
+    def initialize(agent, desk:)
+      @agent = agent
+      @desk = desk
+    end
+
+    # --- Relations ---------------------------------------------------------------
+    #
+    # Every tab states its OWN order, and the base scope states none. An
+    # order baked into the base would win and every later `.order` would be
+    # a dead tiebreaker — which is how a queue quietly starts handing out
+    # the newest ticket when it promised the most urgent one.
+
+    # Every ticket on this desk, newest first — the unfiltered list.
+    def all
+      scoped.newest_first
+    end
+
+    # Open and held by this agent, most urgent first.
+    def mine
+      scoped.open.assigned_to(agent).most_urgent_first
+    end
+
+    # Open and held by nobody, most urgent first.
+    def unassigned
+      scoped.open.unassigned.most_urgent_first
+    end
+
+    # Open and waiting on the desk — the tab that means "work".
+    def awaiting
+      scoped.open.awaiting_reply.most_urgent_first
+    end
+
+    # Put aside until a date, the soonest to wake first (0.2).
+    def snoozed = scoped.snoozed.order(:snoozed_until)
+
+    # Every live case on this desk, held or not, most urgent first.
+    def open = scoped.open.most_urgent_first
+
+    # Done, most recently touched first.
+    def closed = scoped.closed.recent_activity_first
+
+    # --- Numbers -----------------------------------------------------------------
+
+    # Every tab's count, in one grouped query. Grouping by the state columns
+    # (status, awaiting, assignee) and adding up in Ruby costs one round
+    # trip; six `.count` calls cost six.
+    def counts
+      rows = scoped.group(:status, :awaiting, :assignee_type, :assignee_id).count
+
+      counts = TABS.index_with(0)
+      rows.each do |(status, awaiting, assignee_type, assignee_id), count|
+        assigned_to_me = agent_key == [ assignee_type, assignee_id.to_s ]
+
+        case status
+        when "open"
+          counts[:open] += count
+          counts[:mine] += count if assigned_to_me
+          counts[:unassigned] += count if assignee_id.nil?
+          counts[:awaiting] += count if awaiting == "agent"
+        when "snoozed" then counts[:snoozed] += count
+        when "closed" then counts[:closed] += count
+        end
+      end
+      counts
+    end
+
+    # The nav badge: open tickets this agent should feel responsible for —
+    # theirs, plus everything nobody has picked up. Cached briefly per agent.
+    def badge
+      return badge_count unless defined?(Rails) && Rails.respond_to?(:cache) && Rails.cache
+
+      Rails.cache.fetch(badge_cache_key, expires_in: BADGE_TTL) { badge_count }
+    end
+
+    # The ticket to open now: the most urgent among this agent's own and
+    # the unclaimed ones.
+    def next
+      mine_or_unassigned.most_urgent_first.first
+    end
+
+    # [[:awaiting, "Pendientes", 4], …] — i18n labels, in display order,
+    # ready to render.
+    def tabs
+      numbers = counts
+      VISIBLE_TABS.map { |tab| [ tab, I18n.t("support_desk.queue.tabs.#{tab}"), numbers[tab] ] }
+    end
+
+    # The relation behind a tab name, so a console can route `params[:tab]`
+    # without a case statement.
+    def scope(tab)
+      tab = (tab.presence || :awaiting).to_sym
+      raise ArgumentError, "unknown queue tab #{tab.inspect} (known: #{TABS.join(", ")})" unless TABS.include?(tab)
+
+      public_send(tab)
+    end
+
+    # Whose queue, on which desk.
+    def inspect
+      "#<SupportDesk::Queue desk=#{desk.key} agent=#{agent.class}##{agent.id}>"
+    end
+
+    private
+
+    # The base scope: this desk's tickets, in no particular order, so the
+    # caller's order is the one that counts.
+    def scoped
+      Ticket.where(desk: desk)
+    end
+
+    def mine_or_unassigned
+      scoped.open.where(
+        Ticket.arel_table[:assignee_id].eq(nil).or(
+          Ticket.arel_table[:assignee_type].eq(agent.class.polymorphic_name)
+                .and(Ticket.arel_table[:assignee_id].eq(agent.id))
+        )
+      )
+    end
+
+    def badge_count = mine_or_unassigned.count
+
+    def agent_key
+      @agent_key ||= [ agent.class.polymorphic_name, agent.id.to_s ]
+    end
+
+    def badge_cache_key
+      [ "support_desk", "queue", desk.key, "badge", SupportDesk.actor_key(agent) ]
+    end
+  end
+end

data/lib/support_desk/summary.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # One line about a ticket, for places that only have one line: a list row,
+  # a Slack message, the daily Telegram digest, `rails c`.
+  #
+  #   ticket.summary.to_s
+  #   # => "T-AB12CD · Viaje Sevilla → Granada · Alice · esperando respuesta (12 min)"
+  class Summary
+    attr_reader :ticket
+
+    # The one-line summary of a ticket.
+    def initialize(ticket)
+      @ticket = ticket
+    end
+
+    # The pieces, for hosts that want to lay them out themselves.
+    def reference = ticket.reference
+    def label = ticket.label
+
+    # Who is asking, and who is answering (nil while nobody is).
+    def requester_name
+      Chats.display_name_for(ticket.requester)
+    end
+
+    # Who is answering, or nil while nobody is.
+    def assignee_name
+      ticket.assignee&.support_agent_name
+    end
+
+    # "esperando respuesta" / "esperando al cliente" / "cerrado".
+    def state
+      return I18n.t("support_desk.summary.closed") if ticket.closed?
+      return I18n.t("support_desk.summary.awaiting_reply") if ticket.awaiting_reply?
+      return I18n.t("support_desk.summary.awaiting_requester") if ticket.awaiting_requester?
+
+      I18n.t("support_desk.summary.open")
+    end
+
+    # How long the current wait has been going on, as words ("12 minutes").
+    def waiting
+      duration = ticket.waiting_for
+      return nil if duration.nil?
+
+      # Through the same helper the wizard uses for its promise line, so
+      # this speaks the reader's language. Duration#inspect is English
+      # whatever the locale, which left one untranslatable string in an
+      # otherwise Spanish console.
+      Wizard.humanize_duration(duration)
+    end
+
+    # The whole line.
+    def to_s
+      parts = [ reference, label, requester_name, state ]
+      parts << "(#{waiting})" if waiting
+      parts.compact.join(" · ")
+    end
+
+    # The same line, in pieces.
+    def to_h
+      {
+        reference: reference, label: label, requester: requester_name, assignee: assignee_name,
+        state: state, waiting: waiting
+      }
+    end
+
+    # The summary, in one line.
+    def inspect = "#<SupportDesk::Summary #{to_s.inspect}>"
+  end
+end

data/lib/support_desk/test_helpers.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # Test helpers for hosts. Include it in your `ActiveSupport::TestCase`:
+  #
+  #   include SupportDesk::TestHelpers
+  #
+  #   ticket = open_support_ticket(for: users(:alice), about: rides(:sevilla), message: "No aparece")
+  #   reply_as users(:lucia), ticket, "Lo miramos"
+  #   assert_awaiting_requester ticket
+  #   assert_ticket_event ticket, :handed_off, from: users(:lucia), to: users(:pedro)
+  #
+  #   with_support_config(reply_policy: :assignee_only) { … }
+  #
+  # The assertions read the same way the gem's own suite does, which is the
+  # point: your acceptance tests and ours describe the same behaviour.
+  module TestHelpers
+    # Open a ticket the way a requester would, and hand it back.
+    def open_support_ticket(message: "Necesito ayuda", about: nil, topic: nil, **options)
+      requester = options.fetch(:for) { raise ArgumentError, "open_support_ticket needs for: a requester" }
+      requester.ask_support!(message, about: about, topic: topic)
+    end
+
+    # Answer as an agent. Returns the Chats::Message.
+    def reply_as(agent, ticket, body, files: [])
+      ticket.reply!(body, by: agent, files: files)
+    end
+
+    # Say something else as the requester. Returns the Chats::Message.
+    def ask_again(ticket, body)
+      ticket.requester.message!(ticket.conversation, body)
+    end
+
+    # --- Assertions -------------------------------------------------------------
+
+    # The requester spoke last and the desk owes the next word.
+    def assert_awaiting_reply(ticket, message = nil)
+      ticket.reload
+      assert_predicate ticket, :awaiting_reply?,
+                       message || "expected #{ticket.reference} to be waiting on the desk, was #{ticket.awaiting}"
+    end
+
+    # The desk answered and the ball is in the requester's court.
+    def assert_awaiting_requester(ticket, message = nil)
+      ticket.reload
+      assert_predicate ticket, :awaiting_requester?,
+                       message || "expected #{ticket.reference} to be waiting on the requester, " \
+                                  "was #{ticket.awaiting}"
+    end
+
+    # The case is done.
+    def assert_ticket_closed(ticket, message = nil)
+      ticket.reload
+      assert_predicate ticket, :closed?, message || "expected #{ticket.reference} to be closed, was #{ticket.status}"
+    end
+
+    # The case is still live.
+    def assert_ticket_open(ticket, message = nil)
+      ticket.reload
+      assert_predicate ticket, :open?, message || "expected #{ticket.reference} to be open, was #{ticket.status}"
+    end
+
+    # Who is holding the case, or that nobody is.
+    def assert_assigned_to(ticket, agent, message = nil)
+      ticket.reload
+      assert ticket.assigned_to?(agent),
+             message || "expected #{ticket.reference} to be held by #{agent.inspect}, was #{ticket.assignee.inspect}"
+    end
+
+    # Nobody is holding it.
+    def assert_unassigned(ticket, message = nil)
+      ticket.reload
+      assert_predicate ticket, :unassigned?,
+                       message || "expected #{ticket.reference} to be unassigned, was #{ticket.assignee.inspect}"
+    end
+
+    # Assert the ticket's timeline holds an event of +kind+, optionally
+    # matching the actors in its payload.
+    def assert_ticket_event(ticket, kind, from: nil, to: nil, by: nil)
+      events = ticket.events.of_kind(kind).to_a
+      refute_empty events, "expected a #{kind} event on #{ticket.reference}, found " \
+                           "#{ticket.events.map(&:kind).join(", ").presence || "none"}"
+
+      events = events.select { |event| event.payload["from"] == SupportDesk.actor_key(from) } if from
+      events = events.select { |event| event.payload["to"] == SupportDesk.actor_key(to) } if to
+      events = events.select { |event| event.actor == by } if by
+
+      refute_empty events, "expected a #{kind} event on #{ticket.reference} with " \
+                           "#{{ from: from, to: to, by: by }.compact.inspect}"
+      events.first
+    end
+
+    # Assert the case's timeline has NO event of this kind.
+    def refute_ticket_event(ticket, kind)
+      assert_empty ticket.events.of_kind(kind).to_a,
+                   "expected no #{kind} event on #{ticket.reference}"
+    end
+
+    # --- Configuration ----------------------------------------------------------
+
+    # Run a block with different desk settings, then put them back:
+    #
+    #   with_support_config(reply_policy: :assignee_only) { … }
+    #   with_support_config(:billing, reply_within: 1.hour) { … }
+    def with_support_config(desk = :default, **overrides)
+      configuration = SupportDesk.config.desk(desk)
+      previous = overrides.keys.index_with { |key| configuration.read(key) }
+      had = overrides.keys.index_with { |key| configuration.own?(key) }
+
+      overrides.each { |key, value| configuration.public_send(:"#{key}=", value) }
+      yield
+    ensure
+      previous.each do |key, value|
+        had[key] ? configuration.public_send(:"#{key}=", value) : configuration.send(:reset_setting, key)
+      end
+    end
+
+    # Capture the events the gem emits inside the block:
+    #
+    #   events = capture_support_events(:ticket_closed) { ticket.close!(by: lucia) }
+    #
+    # The subscribers are removed again on the way out, block or raise, so a
+    # capture in one example can never fire in the next one.
+    def capture_support_events(*names)
+      captured = []
+      key = :"support_desk_capture_#{SecureRandom.hex(4)}"
+      names.each do |name|
+        SupportDesk.on(name, key: key) { |*args, **kwargs| captured << [ name, args, kwargs ] }
+      end
+
+      yield
+      captured
+    ensure
+      names.each { |name| SupportDesk.off(name, key) }
+    end
+  end
+end

data/lib/support_desk/timeline.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # The whole story of a case in one sequence: what was said and what was
+  # done, merged by time.
+  #
+  #   ticket.timeline.each { |entry| … }
+  #   ticket.timeline.print          # in `rails c`
+  #
+  # Entries wrap either a Chats::Message or a SupportDesk::Event, and answer
+  # the same three questions — when, who, what.
+  class Timeline
+    include Enumerable
+
+    # One moment in a case.
+    class Entry
+      attr_reader :at, :message, :event
+
+      # One moment: a message, or an event, and when it happened.
+      def initialize(at:, message: nil, event: nil)
+        @at = at
+        @message = message
+        @event = event
+      end
+
+      # Which of the two this moment is.
+      def message? = !message.nil?
+      def event? = !event.nil?
+
+      # :message, or the event's kind (:assigned, :closed, :note…).
+      def kind
+        message? ? :message : event.kind.to_sym
+      end
+
+      # Who is responsible for this moment: a message's author (the agent
+      # who signed it) or sender, or an event's actor.
+      def actor
+        return event.actor_or_system if event?
+
+        message.try(:author) || message.sender
+      end
+
+      # What was said, or what a note said. Nil for the rest.
+      def body
+        message? ? message.try(:visible_body) : event.note
+      end
+
+      # Time, kind and the first line of what was said — printable.
+      def to_s
+        "#{at&.iso8601} #{kind} #{body.to_s.truncate(60)}".strip
+      end
+
+      # The entry, in one line.
+      def inspect = "#<SupportDesk::Timeline::Entry #{to_s.inspect}>"
+    end
+
+    attr_reader :ticket
+
+    # The timeline of one ticket.
+    def initialize(ticket)
+      @ticket = ticket
+    end
+
+    # Every moment, oldest first. Enumerable, so map/select/find work.
+    def each(&block)
+      return to_enum(:each) unless block
+
+      entries.each(&block)
+      self
+    end
+
+    # Every moment, oldest first.
+    def entries
+      @entries ||= (message_entries + event_entries).sort_by { |entry| [ entry.at || Time.at(0), entry.kind.to_s ] }
+    end
+
+    # How many moments the case has had, and the latest one.
+    def size = entries.size
+    def last = entries.last
+
+    # Print the case to stdout, for consoles and scripts.
+    def print(io = $stdout)
+      each { |entry| io.puts(entry.to_s) }
+      nil
+    end
+
+    # Which ticket, and how much has happened to it.
+    def inspect = "#<SupportDesk::Timeline #{ticket.reference} #{size} entries>"
+
+    private
+
+    def message_entries
+      return [] if ticket.conversation.nil?
+
+      ticket.conversation.messages.visible.oldest_first.map do |message|
+        Entry.new(at: message.created_at, message: message)
+      end
+    end
+
+    def event_entries
+      ticket.events.chronological.map { |event| Entry.new(at: event.created_at, event: event) }
+    end
+  end
+end