support_desk 0.1.0

data/lib/support_desk/wizard.rb

@@ -0,0 +1,392 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # "What do you need help with?" as a plain object.
+  #
+  # The wizard is the step machine behind the requester-facing screens, and
+  # it is deliberately NOT a controller: a host that ejects the views, a
+  # native app, or a JSON API can all drive the same three steps.
+  #
+  #   wizard = SupportDesk::Wizard.new(alice, params)
+  #   wizard.step       # :topic | :subject | :compose
+  #   wizard.choices    # the topics to offer, or the records to pick from
+  #   wizard.open!("My order never arrived")
+  #
+  # The three steps:
+  #
+  #   1. **Pick a topic.** One level at a time; a branch shows its children,
+  #      a leaf ends the step. Deep-linking a path skips ahead.
+  #   2. **Pick a thing** — only when the leaf attaches something. Candidates
+  #      come from the topic or from the class's own picker, and the ones
+  #      the requester already has an open case about are marked, not hidden.
+  #   3. **Write.** The context card, the prefill, and the composer.
+  #
+  # Subjects arrive as SIGNED GlobalIDs and are re-checked against
+  # `supportable_by?` anyway: a wizard that trusted a raw id would let
+  # anybody open a ticket about anybody's order.
+  class Wizard
+    # What a subject token is signed for, so a token minted for one purpose
+    # can't be replayed at another.
+    SUBJECT_PURPOSE = :support_subject
+
+    # How long a token minted for a DOOR stays good. Doors sit on long-lived
+    # pages and get copied into chats and bug reports, so the link somebody
+    # pastes tomorrow should not still open a wizard.
+    SUBJECT_TOKEN_TTL = 1.hour
+
+    # How long the token the COMPOSER round-trips stays good. It is a hidden
+    # field in a form somebody is typing into, not a link: at one hour, a
+    # person who writes a long message, takes a call and hits Enviar loses
+    # the lot to a 404. Nothing is trusted on the strength of the token
+    # anyway — `supportable_by?` is re-checked on the way in.
+    FORM_TOKEN_TTL = 24.hours
+
+    STEPS = %i[topic subject compose].freeze
+
+    attr_reader :requester, :params
+
+    # Sign a record for a door or a picker link.
+    def self.sign_subject(record, expires_in: SUBJECT_TOKEN_TTL)
+      record.to_sgid(expires_in: expires_in, for: SUBJECT_PURPOSE).to_s
+    end
+
+    # Resolve a signed subject token, or nil when it's missing, expired,
+    # forged, or points at something that has since been deleted.
+    def self.find_signed_subject(token)
+      return nil if token.blank?
+
+      GlobalID::Locator.locate_signed(token.to_s, for: SUBJECT_PURPOSE)
+    rescue StandardError
+      nil
+    end
+
+    # +params+ accepts `topic:` (a path), `subject:` (a signed GlobalID) and
+    # `about:` (a record, for hosts driving the wizard in Ruby).
+    def initialize(requester, params = {}, desk: nil)
+      @requester = requester
+      @params = params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h.symbolize_keys : params.symbolize_keys
+      @desk = desk
+    end
+
+    # The desk this requester writes to.
+    def desk
+      @desk ||= SupportDesk.desk(requester.class.try(:support_desk_key) || :default)
+    end
+
+    # That desk's topic tree.
+    def tree = desk.config.topics
+
+    # Where the ticket will actually be FILED. A topic may hand its subtree
+    # to another desk (`topic :invoice, desk: :billing`), and a ticket
+    # belongs where its topic says, not where the requester's class does.
+    #
+    # Deliberately not folded into #desk: the tree is read from the
+    # requester's desk, and a #desk that depended on the topic would ask the
+    # tree for the topic to find out which tree to ask.
+    def target_desk
+      key = topic&.desk_key
+      return desk if key.nil? || key == desk.key
+
+      SupportDesk.desk(key) || desk
+    end
+
+    # Which step the requester is on, given what they've chosen so far.
+    def step
+      return :topic if topic.nil? || topic.branch?
+      return :subject if needs_subject?
+
+      :compose
+    end
+
+    # Which step this is, for a view that would rather ask than compare.
+    def topic_step? = step == :topic
+    # Picking the thing it's about.
+    def subject_step? = step == :subject
+    # Writing the message.
+    def compose_step? = step == :compose
+
+    # The chosen topic, resolved from the `topic:` param or from the chosen
+    # subject. nil until they've picked one.
+    def topic
+      return @topic if defined?(@topic)
+
+      @topic = resolve_topic
+    end
+
+    # The chosen subject, if any — always re-checked against
+    # `supportable_by?`, never trusted from the params.
+    def subject
+      return @subject if defined?(@subject)
+
+      @subject = resolve_subject
+    end
+
+    # What to render on this step: the topics to offer, or the records to
+    # pick from. Always a collection, never nil.
+    def choices
+      case step
+      when :topic then tree.visible_for(requester, under: topic&.path)
+      when :subject then candidates
+      else []
+      end
+    end
+
+    # The records the picker would offer, resolved once per wizard: the
+    # step machine asks whether there are any, and then the view asks for
+    # them, and a `candidates:` proc that runs a query shouldn't run it twice.
+    def candidates
+      @candidates ||= Array(topic&.candidates_for(requester))
+    end
+
+    # The declared way out of the tree ("Otra cosa"), when this requester may
+    # use it — what a screen with nothing else to offer links to, so a dead
+    # end always has a door in it.
+    def free_form_exit
+      exit_leaf = tree.free_form_leaf
+      exit_leaf if exit_leaf&.visible_for?(requester)
+    end
+
+    # The state this step carries into the next request — what the composer
+    # round-trips as hidden fields, so a POST lands on exactly the step the
+    # GET rendered.
+    def state_params
+      { topic: topic&.path, subject: subject_token, no_subject: (1 if declined_subject?) }.compact
+    end
+
+    # The prompt above the choices.
+    def ask
+      case step
+      when :topic then topic&.ask || I18n.t("support_desk.wizard.ask_topic")
+      when :subject then topic.ask || I18n.t("support_desk.wizard.ask_subject")
+      end
+    end
+
+    # Whether the picker should offer "none of these".
+    def subject_optional?
+      subject_step? && topic.subject_mode == :optional
+    end
+
+    # Text to drop into the composer, from the topic's `prefill:`.
+    def prefill
+      topic&.prefill(subject)
+    end
+
+    # The composer's placeholder for this topic.
+    def placeholder
+      topic&.placeholder || I18n.t("support_desk.wizard.placeholder")
+    end
+
+    # The promise shown next to the composer ("we usually reply in under a
+    # day"), built from `config.reply_within` — one setting, one truth: the
+    # same number the SLA breaches on.
+    def promise
+      return nil if promise_within.nil?
+
+      I18n.t("support_desk.thread.promise", time: self.class.humanize_duration(promise_within))
+    end
+
+    # The promise as a Duration, for hosts that want to phrase it themselves.
+    def promise_within = desk.config.reply_within
+
+    # "1 day", "4 horas" — through ActionView's date helper so it speaks the
+    # requester's language, falling back to Duration#inspect in the (rare)
+    # app that has no ActionView.
+    def self.humanize_duration(duration)
+      return duration.inspect unless defined?(ActionView::Helpers::DateHelper)
+
+      @duration_words ||= Object.new.extend(ActionView::Helpers::DateHelper)
+      words = @duration_words.distance_of_time_in_words(duration.to_i).to_s
+      # An app whose locale has no date translations (no rails-i18n) would
+      # otherwise show "Translation missing" to a customer.
+      words.start_with?("Translation missing") ? duration.inspect : words
+    end
+
+    # The open case this would land in, when the requester already has one
+    # about this thing — so the wizard can say "you already have a
+    # conversation open" and link to it instead of opening a second.
+    def existing_ticket
+      return nil if topic.nil? || topic.branch?
+
+      key = Ticket.cardinality_key_for(requester: requester, subject: subject, topic: topic)
+      return nil if key.start_with?("free:")
+
+      Ticket.not_closed.find_by(requester: requester, desk: target_desk, cardinality_key: key)
+    end
+
+    # Which records in +choices+ the requester already has an open case
+    # about, so the picker can mark them. One query per wizard, not one per
+    # row.
+    def open_tickets_by_subject
+      return @open_tickets_by_subject if defined?(@open_tickets_by_subject)
+
+      @open_tickets_by_subject =
+        if subject_step?
+          Ticket.not_closed.where(requester: requester, desk: target_desk)
+                .where.not(subject_id: nil)
+                .index_by { |ticket| [ ticket.subject_type, ticket.subject_id.to_s ] }
+        else
+          {}
+        end
+    end
+
+    # The open case this requester already has about +record+, or nil — what
+    # the picker marks with "Ya tienes una conversación abierta" and links to
+    # instead of offering as a choice.
+    def open_ticket_about(record)
+      return nil if record.nil?
+
+      open_tickets_by_subject[[ record.class.polymorphic_name, record.id.to_s ]]
+    end
+
+    # True when the params named a subject that didn't resolve: a forged or
+    # expired token, a record that has since been deleted, one that isn't
+    # supportable, or somebody else's. Callers turn this into a 404 — "not
+    # yours" and "not there" must look the same from outside.
+    def subject_rejected?
+      subject_named? && subject.nil?
+    end
+
+    # The params that take the requester one step back, or nil when this is
+    # the first screen. An empty Hash means the top of the topic tree, so
+    # `new_ticket_path(wizard.back)` is always the right link — the wizard
+    # never leans on `history.back()`, because every step is a real URL.
+    def back
+      case step
+      when :topic then topic && level_above(topic)
+      when :subject then level_above(topic)
+      when :compose
+        # A door dropped them straight here from a host page. "Back" to a
+        # picker they never saw would be a place they have never been.
+        return nil if subject_named? && params[:topic].blank?
+
+        picker_step? ? { topic: topic.path } : level_above(topic)
+      end
+    end
+
+    # Submit. Raises SupportDesk::InvalidTransition when the wizard isn't
+    # finished — a host that renders its own form can't half-submit one.
+    def open!(message, files: [])
+      unless compose_step?
+        raise InvalidTransition, "the wizard is still on the #{step} step — pick one before submitting"
+      end
+
+      # `ask_support!` files under the REQUESTER's desk, which is right
+      # until a topic says otherwise; then the redirect is spelled out.
+      if target_desk == desk
+        requester.ask_support!(message, about: subject, topic: topic.path, files: files)
+      else
+        Ticket.open!(requester: requester, message: message, about: subject, topic: topic.path,
+                     files: files, desk: target_desk,
+                     requester_role: requester.class.support_desk_requester_options[:as])
+      end
+    end
+
+    # A signed token for the currently chosen subject, to round-trip through
+    # the next form — on the form's clock, not a door's (see FORM_TOKEN_TTL).
+    def subject_token
+      subject && self.class.sign_subject(subject, expires_in: FORM_TOKEN_TTL)
+    end
+
+    # Where the requester has got to, in one line.
+    def inspect
+      "#<SupportDesk::Wizard step=#{step} topic=#{topic&.path.inspect} subject=#{subject.inspect}>"
+    end
+
+    private
+
+    def needs_subject?
+      return false if topic.nil? || topic.free_form?
+      return false if subject
+      return false if topic.about.empty?
+
+      return false if topic.subject_mode == :none
+      # "None of these" is only on offer when the topic said it was optional.
+      return false if declined_subject?
+      # Nothing to pick from and nothing insisting we pick: asking "which
+      # one?" above an empty list is a dead end, so skip straight to writing.
+      return false if candidates.empty? && topic.subject_mode != :required
+
+      true
+    end
+
+    # Whether they answered "ninguno de estos" — only an answer at all when
+    # the topic offered it.
+    def declined_subject?
+      params.key?(:no_subject) && topic&.subject_mode == :optional
+    end
+
+    # True when the params tried to name a subject at all — used to tell
+    # "they haven't picked one yet" apart from "the one they named is not
+    # theirs".
+    def subject_named?
+      params[:about].present? || params[:subject].present?
+    end
+
+    # Whether this topic has a picker that would actually RENDER — which is
+    # what decides where "back" from the composer goes. A picker skipped for
+    # having nothing in it must not be the place back leads to, or back
+    # forwards straight to where it came from.
+    def picker_step?
+      return false if topic.nil? || topic.free_form? || topic.about.empty?
+      return true if topic.subject_mode == :required
+
+      candidates.any?
+    end
+
+    # The params for the level of the tree +node+ was chosen from: its
+    # parent branch, or the top level ({}).
+    def level_above(node)
+      node&.parent ? { topic: node.parent.path } : {}
+    end
+
+    def resolve_topic
+      path = params[:topic].presence
+      chosen = path ? nil : resolve_subject
+      node = if path
+               tree.find(path.to_s)
+      elsif chosen
+               tree.find(chosen.support_topic.to_s)
+      end
+
+      # A deep link is a list of one: a topic this requester would never be
+      # offered is not one they may walk into by typing its path — nor by
+      # pointing at a record whose own `support_topic` is hidden from them,
+      # which is the same bypass wearing a different hat.
+      return node&.visible_for?(requester) ? node : nil if path || chosen
+
+      # Nothing on offer at all: every branch behind an `only:`, or a desk
+      # with no tree. The wizard must not open on a question with no
+      # answers, so it starts at the composer under the DECLARED way out
+      # (`other`, or `free_form: true`) — and only when that leaf is one
+      # this requester may use, because `Ticket.open!` refuses a hidden
+      # topic and a composer that 404s on submit is worse than a refusal.
+      #
+      # nil when the tree declares no exit, or hides the one it declares:
+      # the requester stays on the topic step with nothing to choose, and
+      # the screen says so.
+      return nil unless tree.visible_for(requester).empty?
+
+      free_form_exit
+    end
+
+    def resolve_subject
+      record = subject_from_params
+      return nil if record.nil?
+      return nil unless record.respond_to?(:supportable?) && record.supportable?
+      return nil unless record.supportable_by?(requester)
+
+      record
+    end
+
+    # `about:` is the one param a door, a deep link and a host driving the
+    # wizard in Ruby all use, so it accepts BOTH: a signed GlobalID off the
+    # query string, or the record itself. `subject:` is the same token under
+    # the name the wizard's own forms round-trip it as.
+    def subject_from_params
+      given = params[:about]
+      return given unless given.nil? || given.is_a?(String)
+
+      self.class.find_signed_subject(given.presence || params[:subject])
+    end
+  end
+end

data/lib/support_desk.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/string/inflections"
+require "active_support/core_ext/hash/keys"
+require "active_support/core_ext/object/blank"
+require "global_id"
+
+require "chats"
+
+require_relative "support_desk/version"
+require_relative "support_desk/errors"
+require_relative "support_desk/events"
+require_relative "support_desk/topic"
+require_relative "support_desk/topic_tree"
+require_relative "support_desk/configuration"
+require_relative "support_desk/current"
+require_relative "support_desk/macros"
+# The console's Layer 2. Spine rather than autoloaded, because the engine
+# isolates SupportDesk::Console as its namespace and a namespace has to
+# exist before an engine can isolate it.
+require_relative "support_desk/console"
+require_relative "support_desk/console_routes"
+
+if defined?(::Rails::Engine)
+  require_relative "support_desk/engine"
+  require_relative "support_desk/console_engine"
+end
+
+# == SupportDesk
+#
+# Customer support for Rails apps: tickets that are conversations. A product
+# gem on the `chats` kernel — chats owns the transcript, support_desk owns
+# the case.
+#
+# The public surface is small on purpose:
+#
+#   SupportDesk.configure { |config| ... }   # one block, in an initializer
+#   has_support_tickets                      # on whoever asks for help
+#   supportable topic: :ride                 # on whatever they ask about
+#   acts_as_support_agent if: :admin?        # on whoever answers
+#
+#   ticket = alice.ask_support!("No me han pagado", about: withdrawal)
+#   ticket.assign!(to: lucia)
+#   ticket.reply!("Lo estamos revisando", by: lucia)
+#   ticket.close!(by: lucia)
+#
+# Everything else is queues, presenters and events — see the README.
+module SupportDesk
+  # Assertions and builders for host test suites. Autoloaded, the way
+  # organizations and clickwrap expose theirs, so a host writes
+  # `include SupportDesk::TestHelpers` without a require and a production
+  # boot never loads the file.
+  autoload :TestHelpers, "support_desk/test_helpers"
+
+  class << self
+    include Events
+
+    # --- Configuration --------------------------------------------------------
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    alias configuration config
+
+    # The one block a host writes, in an initializer. Validates what it
+    # can right away; the checks that need the app's own classes run at
+    # the first prepare.
+    def configure
+      yield config if block_given?
+      config.validate!
+      @configured = true
+      config
+    end
+
+    # Whether a host has actually run `SupportDesk.configure`. Boot-time
+    # class validation only bites once they have: a fresh `bundle add
+    # support_desk` must still boot so you can run the install generator.
+    def configured?
+      !!@configured
+    end
+
+    # Reset the global state a test can dirty: configuration, subscribers,
+    # and the memoised desks. Handy in a console too.
+    #
+    # The class registries are deliberately NOT cleared: they are a property
+    # of the code that is loaded (the macros register at class definition
+    # time), not of the configuration, and a host test suite shouldn't have
+    # to re-declare its own models between examples.
+    def reset!
+      @config = Configuration.new
+      @configured = false
+      @subscribers = nil
+      @desks = nil
+      self
+    end
+
+    # Forget the memoised Desk records without touching configuration — for
+    # tests that truncate tables between examples.
+    def reset_desks!
+      @desks = nil
+      self
+    end
+
+    # --- Desks ------------------------------------------------------------------
+
+    # The desk record for +key+, memoised per process.
+    #
+    # Lazily created with `find_by || create_or_find_by!` and NEVER
+    # INSERT-first: a desk is read thousands of times and written once, and
+    # an INSERT that fails its unique index on every page view is noise in
+    # the log and a wasted round trip.
+    def desk(key = :default)
+      key = (key || :default).to_sym
+      return nil unless config.desk?(key) || key == :default
+
+      desks[key] ||= Desk.for(key)
+    end
+
+    # Every desk record this process has resolved, keyed by key.
+    def desks # :nodoc:
+      @desks ||= {}
+    end
+
+    # --- Topics -----------------------------------------------------------------
+
+    # The Topic at +path+, looked up across every configured desk's tree, or
+    # a Topic::Unknown that still renders (never raises in a view).
+    def find_topic(path)
+      return nil if path.nil?
+
+      path = path.to_s
+      config.desks.each_value do |desk|
+        node = desk.topics.find(path)
+        return node if node
+      end
+
+      Topic::Unknown.new(path)
+    end
+
+    # --- Registries ---------------------------------------------------------------
+    #
+    # The macros self-register the calling class here. We store class NAMES
+    # (strings), not Class objects, so the registry survives Zeitwerk code
+    # reloading in development (a reloaded class is a brand new object; its
+    # name is stable).
+
+    # Called by the macros. Returns the class, so it composes.
+    def register_requester(klass) = register(requester_class_names, klass)
+    def register_supportable(klass) = register(supportable_class_names, klass)
+    # Called by `acts_as_support_agent`. Returns the class.
+    def register_agent(klass) = register(agent_class_names, klass)
+
+    # The registered class names, as Sets of Strings.
+    def requester_class_names = @requester_class_names ||= Set.new
+    def supportable_class_names = @supportable_class_names ||= Set.new
+    # Every class that has declared itself able to answer.
+    def agent_class_names = @agent_class_names ||= Set.new
+
+    # Whether +klass+ (a Class, an instance, or a class name) is supportable.
+    def supportable_class?(klass) = registered?(supportable_class_names, klass)
+    # Whether +klass+ asks for support / answers it. Ancestor-aware, so an
+    # STI subclass of a registered class counts.
+    def requester_class?(klass) = registered?(requester_class_names, klass)
+    def agent_class?(klass) = registered?(agent_class_names, klass)
+
+    # --- The chats seam -------------------------------------------------------------
+
+    # Subscribe the gem's own `:message_created` listener, which is what
+    # keeps `awaiting`, the SLA clocks and reopen-on-reply true without
+    # anybody remembering to call anything.
+    #
+    # Safe to call as often as you like: chats replaces a subscriber
+    # registered under the same `key:` rather than stacking another one.
+    # There is deliberately NO "already subscribed" flag here — one would
+    # make re-subscribing after a `Chats.reset!` a silent no-op, and the
+    # first sign of that is a desk whose tickets stop knowing whose turn it
+    # is, with nothing in the log.
+    def subscribe_to_chats!
+      Chats.on(:message_created, key: :support_desk) do |message|
+        # The constant is resolved on every call on purpose: in development
+        # the Ticket class is a new object after each reload.
+        SupportDesk::Ticket.for_conversation(message.conversation)&.register!(message)
+      end
+      self
+    end
+
+    # --- Health -------------------------------------------------------------------
+
+    # Everything that can only be checked against a running app:
+    # configuration, the chats seams, and the data invariants.
+    # `SupportDesk.doctor.ok?` is the one line to put in CI.
+    def doctor = Doctor.run
+
+    # --- Internals ----------------------------------------------------------------
+
+    def logger
+      defined?(::Rails) ? ::Rails.logger : nil
+    end
+
+    # Where the host mounted the requester-facing engine
+    # ("/messages/support"), or nil when they haven't. Used for the grouped
+    # inbox row's link and by `doctor`.
+    #
+    # Read from the route set rather than from a URL helper on purpose: the
+    # answer has to exist before the engine has drawn a single route.
+    def root_path
+      return nil unless defined?(::Rails) && ::Rails.application
+
+      route = ::Rails.application.routes.routes.find do |candidate|
+        candidate.app.respond_to?(:app) && candidate.app.app == SupportDesk::Engine
+      end
+      return nil unless route
+
+      path = route.path.spec.to_s.sub("(.:format)", "")
+      path.empty? ? "/" : path
+    rescue StandardError
+      nil
+    end
+
+    # The Hotwire Native path-configuration rules for the requester-facing
+    # engine, ready to splat into a host's own `rules` array:
+    #
+    #   rules: [ *SupportDesk.native_path_rules, *my_own_rules ]
+    #
+    # Both surfaces are ordinary PUSHED screens (`context: "default"`), never
+    # modals: the wizard is three real URLs and a modal would break the back
+    # gesture between them. The thread itself is deliberately absent — it is
+    # a chats conversation, and it stays under the host's chats rule.
+    #
+    # +mount+ defaults to wherever the engine is mounted and +title+ to the
+    # desk's name.
+    def native_path_rules(mount: nil, title: nil)
+      mount = (mount || root_path)&.to_s&.chomp("/")
+      if mount.blank?
+        raise ConfigurationError,
+              "SupportDesk.native_path_rules can't tell where the engine is mounted. " \
+              "Mount it (`mount SupportDesk::Engine => \"/support\"`) or pass mount: \"/support\"."
+      end
+
+      title ||= config.name
+      prefix = Regexp.escape(mount)
+
+      [
+        {
+          patterns: [ "^#{prefix}/?(?:\\?.*)?$" ],
+          properties: { context: "default", title: title, pull_to_refresh_enabled: true },
+          comment: "The requester's support list: a pushed screen, pull to refresh like any other list."
+        },
+        {
+          patterns: [ "^#{prefix}/new(?:\\?.*)?$" ],
+          properties: { context: "default", title: title, pull_to_refresh_enabled: false },
+          comment: "The wizard: every step is a real URL, so it pushes and the back gesture works. " \
+                   "Pull to refresh is off — it would throw away what the requester has typed."
+        }
+      ]
+    end
+
+    # A stable, URL-safe key for an actor (agent, requester, desk), used in
+    # cache keys and event payloads. GlobalID params already encode class +
+    # id, so two classes can never collide.
+    def actor_key(record)
+      return nil if record.nil?
+      return record.to_s if record.is_a?(Symbol)
+
+      record.to_global_id.to_param
+    end
+
+    private
+
+    def register(registry, klass)
+      registry << klass.name if klass.name
+      klass
+    end
+
+    def registered?(registry, klass)
+      klass = klass.class unless klass.is_a?(Class) || klass.is_a?(String)
+      name = klass.is_a?(String) ? klass : klass.name
+      return true if registry.include?(name)
+
+      constant = klass.is_a?(String) ? name.safe_constantize : klass
+      return false unless constant.respond_to?(:ancestors)
+
+      constant.ancestors.any? { |ancestor| registry.include?(ancestor.name) }
+    end
+  end
+end