support_desk 0.1.3 → 0.2.0

data/lib/support_desk/macros.rb

@@ -20,11 +20,15 @@ module SupportDesk
   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)
+    # console can tell two kinds of requester apart; `if:` is the per-record
+    # check for "may this person ask for help — and be written to — right
+    # now" (`if: :kept?` for a host with soft-deleted accounts).
+    def has_support_tickets(desk: :default, as: nil, **options)
+      condition = Macros.condition!(options, macro: "has_support_tickets", known: ":if, :desk, :as")
+
       include SupportDesk::Requester
 
-      self.support_desk_requester_options = { desk: desk.to_sym, as: as&.to_s }.freeze
+      self.support_desk_requester_options = { desk: desk.to_sym, as: as&.to_s, if: condition }.freeze
       SupportDesk.register_requester(self)
     end
 
@@ -48,26 +52,38 @@ module SupportDesk
 
     # 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.
+    # One verb is added — `open_support_conversation_with!`, the only agent
+    # action that has no ticket yet. Everything else keeps the ticket as the
+    # subject of the sentence (`ticket.assign!(to: lucia)`).
     def acts_as_support_agent(kind: :human, **options)
+      condition = Macros.condition!(options, macro: "acts_as_support_agent", known: ":if, :kind")
+
+      include SupportDesk::Agent
+
+      self.support_desk_agent_options = { if: condition, kind: kind.to_sym }.freeze
+      SupportDesk.register_agent(self)
+    end
+
+    # The `if:` both macros take: a method name or a callable, and the only
+    # option either of them accepts beyond its own keywords. Written once
+    # because "may this person answer" and "may this person ask" are the same
+    # question asked of a different side, and two copies of it would be two
+    # places to fix the day one grows a third shape.
+    def self.condition!(options, macro:, known:)
       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"
+              "unknown #{macro} option#{"s" if unknown.size > 1} " \
+              "#{unknown.map(&:inspect).join(", ")} — known options are #{known}"
       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}"
+              "#{macro} 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)
+      condition
     end
   end
 end

data/lib/support_desk/models/assignment.rb

@@ -11,7 +11,9 @@ module SupportDesk
   class Assignment < ApplicationRecord
     self.table_name = "support_desk_assignments"
 
-    REASONS = %w[taken assigned handed_off routed drop_in_takeover escalated reopened].freeze
+    # `opened`: the agent who wrote first holds the case. It is a seat nobody
+    # was told about — see Ticket.open!(by:) — not an assignment somebody made.
+    REASONS = %w[taken assigned handed_off routed drop_in_takeover escalated reopened opened].freeze
     RELEASE_REASONS = %w[handed_off released shift_end closed escalated].freeze
 
     belongs_to :ticket, class_name: "SupportDesk::Ticket", inverse_of: :assignments

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

@@ -38,11 +38,46 @@ module SupportDesk
     # 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)
+      SupportDesk.eligible?(self, self.class.support_desk_agent_options[:if])
+    end
+
+    # Write first, as the desk — the mirror of Requester#ask_support!.
+    #
+    #   lucia.open_support_conversation_with!(alice, "Vimos que tu retirada rebotó", about: withdrawal)
+    #   lucia.open_support_conversation_with!(alice, "Tu DNI no se lee bien", topic: :verification)
+    #
+    # Not `message!`: that is a personal chat from Lucía. This speaks as the
+    # desk, signs the message with her name, seats her on the case, and lands
+    # in Alice's inbox as "Soporte". If Alice already has this conversation
+    # open, the message joins it as an ordinary reply, under the desk's reply
+    # policy — which can leave the case with whoever already holds it.
+    # Returns the SupportDesk::Ticket.
+    #
+    # Raises NotARequester (nobody to write to), NotAllowed (including an
+    # agent aiming at themselves: an agent who needs help asks for it),
+    # NotSupportable, UnknownTopic.
+    def open_support_conversation_with!(requester, message, about: nil, topic: nil, files: [], via: :in_app,
+                                        desk: nil, request: nil)
+      SupportDesk::Ticket.ensure_requester!(requester)
+
+      if SupportDesk::Ticket.same_actor?(requester, self)
+        raise SupportDesk::NotAllowed,
+              "#{self.class}##{id} can't open a support conversation with themselves — an agent who needs " \
+              "help asks for it (ask_support!), and the case would be theirs to answer"
+      end
 
-      !!condition.call(self)
+      SupportDesk::Ticket.open!(
+        requester: requester,
+        by: self,
+        message: message,
+        about: about,
+        topic: topic,
+        files: files,
+        via: via,
+        desk: desk || requester.support_desk,
+        requester_role: requester.class.support_desk_requester_options[:as],
+        request: request
+      )
     end
 
     # :human or :ai. Bots disclose themselves through this (04).

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

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 module SupportDesk
-  # Included by `has_support_tickets`. Adds exactly four methods — the whole
-  # requester side of the gem:
+  # Included by `has_support_tickets`. The whole requester side of the gem:
   #
   #   alice.ask_support!("El viaje no aparece verificado", about: ride)
   #   alice.support_tickets.open.about(ride)
+  #   alice.support_requester?
+  #   alice.support_desk
   #   alice.awaiting_support_reply?
   #   alice.unread_support_count
   module Requester
@@ -13,7 +14,7 @@ module SupportDesk
 
     included do
       class_attribute :support_desk_requester_options, instance_writer: false,
-                                                       default: { desk: :default, as: nil }.freeze
+                                                       default: { desk: :default, as: nil, if: nil }.freeze
 
       has_many :support_tickets,
                class_name: "SupportDesk::Ticket",
@@ -26,6 +27,26 @@ module SupportDesk
       def support_desk_key = support_desk_requester_options[:desk]
     end
 
+    # Whether this record may ask for help — or be written to — right now:
+    # the `if:` condition from `has_support_tickets`, honoured. A closed
+    # account answers false and can do neither, while its history stays
+    # readable (see Ticket#chat_locked?).
+    def support_requester?
+      SupportDesk.eligible?(self, self.class.support_desk_requester_options[:if])
+    end
+
+    # The desk this requester writes to (`has_support_tickets desk:`), as a
+    # record. Raises ConfigurationError naming the fix when that desk isn't
+    # configured — its tickets would otherwise silently land on the default
+    # desk.
+    def support_desk
+      key = self.class.support_desk_key
+      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")
+    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).
@@ -33,15 +54,9 @@ module SupportDesk
     #   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.
+    # Raises NotARequester, 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,
@@ -49,7 +64,7 @@ module SupportDesk
         topic: topic,
         files: files,
         via: via,
-        desk: desk,
+        desk: support_desk,
         requester_role: self.class.support_desk_requester_options[:as]
       )
     end