support_desk 0.1.0

data/lib/support_desk/topic.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require "active_model/type"
+
+module SupportDesk
+  # What a ticket is about, as a value object.
+  #
+  # Topics are a tree defined in code (see SupportDesk::TopicTree), frozen at
+  # boot, and stored on the ticket as a stable path — `"payments/withdrawal"`
+  # — so seeds, exports and metrics stay readable and re-ordering the tree
+  # never rewrites a single row.
+  #
+  #   ticket.topic                      # => #<SupportDesk::Topic payments/withdrawal>
+  #   ticket.topic == :ride             # compares against the path
+  #   ticket.topic.under?(:payments)    # self or any descendant
+  #   ticket.topic.label                # "Una retirada" (i18n)
+  #   ticket.topic.to_s                 # "payments/withdrawal"
+  #
+  # Immutable: every node is frozen once the tree is built.
+  class Topic
+    # Options a branch passes down to its descendants unless they say
+    # otherwise. Presentation (label, ask, prefill) is never inherited — only
+    # the options that carry behaviour.
+    INHERITED_OPTIONS = %i[about candidates desk route_to priority only retired].freeze
+
+    SUBJECT_MODES = %i[required optional none].freeze
+    PRIORITIES = { normal: 0, high: 1, urgent: 2 }.freeze
+
+    attr_reader :key, :path, :parent, :children, :options
+
+    # Nodes are built by the topics DSL, never by hand.
+    def initialize(key:, parent: nil, **options)
+      @key = key.to_sym
+      @parent = parent
+      @path = [ parent&.path, @key ].compact.join("/")
+      @options = options.freeze
+      @children = []
+    end
+
+    # --- Tree shape -----------------------------------------------------------
+
+    # Top level, nothing below it, or something below it.
+    def root? = parent.nil?
+    # Nothing below it.
+    def leaf? = children.empty?
+    # Something below it.
+    def branch? = !leaf?
+
+    # Every ancestor, closest first.
+    def ancestors
+      parent ? [ parent, *parent.ancestors ] : []
+    end
+
+    # This node and every node below it, depth first.
+    def self_and_descendants
+      [ self, *children.flat_map(&:self_and_descendants) ]
+    end
+
+    # --- Identity -------------------------------------------------------------
+
+    def to_s = path
+    # The path, for URLs.
+    def to_param = path
+
+    # True for the null object returned for paths that aren't in the tree.
+    def unknown? = false
+
+    # Compares against a Topic, a path String, or a Symbol key/path, so
+    # `ticket.topic == :ride` reads the way you'd say it.
+    def ==(other)
+      case other
+      when Topic then path == other.path
+      when String, Symbol then path == other.to_s
+      else false
+      end
+    end
+    alias eql? ==
+
+    # Hashes by path, so topics work as Hash keys.
+    def hash = path.hash
+
+    # True when this topic is +other+ or lives under it:
+    # `topic("payments/withdrawal").under?(:payments)`.
+    def under?(other)
+      other = other.to_s
+      path == other || path.start_with?("#{other}/")
+    end
+
+    # --- Presentation ---------------------------------------------------------
+
+    # The human name of this node, from `label:` or i18n
+    # (`support_desk.topics.<dotted path>.label`), falling back to a
+    # humanized key so a missing translation is never a missing screen.
+    def label
+      case options[:label]
+      when String then options[:label]
+      when Symbol then translate(i18n_key_for(options[:label], :label)) || key.to_s.humanize
+      else translate(i18n_key(:label)) || key.to_s.humanize
+      end
+    end
+
+    # The whole branch spelled out: "Pagos › Una retirada".
+    def full_label
+      [ *ancestors.reverse, self ].map(&:label).join(" › ")
+    end
+
+    # The picker prompt ("¿Con qué viaje necesitas ayuda?").
+    def ask
+      options[:ask].is_a?(String) ? options[:ask] : translate(i18n_key(:ask))
+    end
+
+    # The composer placeholder for tickets opened under this topic.
+    def placeholder
+      options[:placeholder].is_a?(String) ? options[:placeholder] : translate(i18n_key(:placeholder))
+    end
+
+    # Deterministic text dropped into the composer. `prefill:` may be a String
+    # or a callable taking the chosen subject.
+    def prefill(subject = nil)
+      value = options[:prefill]
+      value.respond_to?(:call) ? value.call(subject) : value
+    end
+
+    # An optional icon key for hosts that render one; the gem never does.
+    def icon = options[:icon]
+
+    # --- Behaviour ------------------------------------------------------------
+
+    # The `supportable` classes a ticket under this topic may attach, as
+    # Classes. Resolved lazily from stored names so the tree survives
+    # Zeitwerk reloads.
+    def about
+      Array(inherited_or_own(:about)).map { |klass| klass.is_a?(String) ? klass.constantize : klass }
+    end
+
+    # Whether this topic attaches +klass+ (or an instance of it).
+    def about?(klass)
+      about.any? { |candidate| klass.is_a?(Class) ? klass <= candidate : klass.class <= candidate }
+    end
+
+    # Stored (unconstantized) `about:` class names — what boot validation and
+    # `doctor` check, without forcing the classes to load.
+    def about_class_names
+      Array(inherited_or_own(:about)).map { |klass| klass.is_a?(String) ? klass : klass.name }
+    end
+
+    # :required — the wizard insists on a subject; :optional — it offers
+    # "none of these"; :none — free form. Defaults to :optional when the
+    # topic attaches anything at all, :none when it doesn't.
+    def subject_mode
+      options.fetch(:subject) { about.any? ? :optional : :none }.to_sym
+    end
+
+    # Whether the wizard insists on a subject, or asks for none at all.
+    def subject_required? = subject_mode == :required
+    def free_form? = subject_mode == :none
+
+    # Whether this node is the tree's declared way out — what `other`
+    # builds, or any leaf a host declared `free_form: true`.
+    #
+    # Deliberately NOT the same question as #free_form?: plenty of topics
+    # take no subject ("app feedback", "safety") without being the place a
+    # ticket should land when nobody picked anything.
+    def catch_all? = !!options[:free_form]
+
+    # The picker's candidate records for +requester+: the topic's
+    # `candidates:` proc, else each `about:` class's own
+    # `.support_candidates_for`.
+    def candidates_for(requester)
+      proc = inherited_or_own(:candidates)
+      return proc.call(requester) if proc.respond_to?(:call)
+
+      about.first&.support_candidates_for(requester)
+    end
+
+    # Whether this node shows in the wizard for +requester+ (`only:` proc,
+    # and retired nodes never do).
+    def visible_for?(requester)
+      return false if retired?
+
+      only = inherited_or_own(:only)
+      only.respond_to?(:call) ? !!only.call(requester) : true
+    end
+
+    # 0 normal, 1 high, 2 urgent — the integer a ticket is opened with.
+    def priority
+      PRIORITIES.fetch((inherited_or_own(:priority) || :normal).to_sym, 0)
+    end
+
+    # An agent scope or proc that wins over desk routing for this subtree.
+    def route_to = inherited_or_own(:route_to)
+
+    # The desk key tickets under this topic belong to.
+    def desk_key
+      (inherited_or_own(:desk) || :default).to_sym
+    end
+
+    # Hidden from the wizard; the label still resolves for historic tickets.
+    def retired? = !!inherited_or_own(:retired)
+
+    # The topic, in one line.
+    def inspect = "#<SupportDesk::Topic #{path}>"
+
+    # Freeze this node and everything under it — the tree is built once, at
+    # boot, and then it is a value.
+    def deep_freeze # :nodoc:
+      children.each(&:deep_freeze)
+      children.freeze
+      freeze
+    end
+
+    # Used by the DSL while the tree is being built.
+    def add_child(child) # :nodoc:
+      children << child
+      child
+    end
+
+    private
+
+    def inherited_or_own(option)
+      return options[option] if options.key?(option)
+      return nil unless INHERITED_OPTIONS.include?(option)
+
+      parent&.send(:inherited_or_own, option)
+    end
+
+    def i18n_key(suffix)
+      "support_desk.topics.#{path.tr("/", ".")}.#{suffix}"
+    end
+
+    def i18n_key_for(symbol, suffix)
+      symbol.to_s.include?(".") ? symbol.to_s : "support_desk.topics.#{symbol}.#{suffix}"
+    end
+
+    def translate(key)
+      return nil unless defined?(I18n)
+
+      I18n.t(key, default: nil)
+    end
+
+    # The null object for a path no tree knows: a retired node whose label
+    # still reads well, so a historic ticket never blows up a view.
+    #
+    #   ticket.topic.unknown?   # => true
+    #   ticket.topic.label      # => "Payments/withdrawal"
+    class Unknown < Topic
+      def initialize(path)
+        super(key: path.to_s.split("/").last || path.to_s)
+        @path = path.to_s
+      end
+
+      def unknown? = true
+      def retired? = true
+      def label = translate(i18n_key(:label)) || @path.tr("/", " ").humanize
+      def about = []
+      def subject_mode = :none
+      def inspect = "#<SupportDesk::Topic::Unknown #{path}>"
+    end
+
+    # The ActiveModel attribute type behind `attribute :topic`: casts
+    # Symbol | String | Topic on the way in, hands back a Topic on the way
+    # out, and serializes to the path — so `where(topic: :ride)` works and a
+    # view never sees a bare string.
+    class Type < ActiveModel::Type::Value
+      def type = :string
+
+      def cast(value)
+        case value
+        when nil then nil
+        when Topic then value
+        else SupportDesk.find_topic(value.to_s)
+        end
+      end
+
+      def serialize(value)
+        case value
+        when nil then nil
+        when Topic then value.path
+        else value.to_s
+        end
+      end
+
+      def deserialize(value) = cast(value)
+
+      def changed_in_place?(raw_old_value, new_value)
+        raw_old_value != serialize(new_value)
+      end
+    end
+  end
+end

data/lib/support_desk/topic_tree.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require_relative "topic"
+
+module SupportDesk
+  # The tree of topics a desk offers, built once at boot from the `topics`
+  # block and frozen:
+  #
+  #   config.topics do
+  #     topic :ride, about: Ride
+  #     topic :payments do
+  #       topic :withdrawal, about: Payouts::Withdrawal
+  #     end
+  #     other
+  #   end
+  #
+  # It is the one object the wizard, the console picker, routing and metrics
+  # all read: `tree.find("payments/withdrawal")`, `tree.visible_for(user)`,
+  # `tree.leaves`.
+  class TopicTree
+    include Enumerable
+
+    # The free-form leaf every tree should have — a taxonomy without an exit
+    # is how people pick the wrong topic.
+    OTHER_KEY = :other
+
+    attr_reader :roots
+
+    # Build a tree from a `topics do … end` block, and freeze it.
+    def self.build(&block)
+      new.tap { |tree| Builder.new(tree).instance_eval(&block) if block }.freeze!
+    end
+
+    # An empty tree. Prefer `TopicTree.build`.
+    def initialize
+      @roots = []
+      @index = {}
+    end
+
+    # Depth-first over every node.
+    def each(&block)
+      return to_enum(:each) unless block
+
+      @roots.each { |root| root.self_and_descendants.each(&block) }
+      self
+    end
+
+    # The node at +path+ ("payments/withdrawal"), or nil.
+    def find(path)
+      return nil if path.nil?
+
+      @index[path.to_s]
+    end
+    alias [] find
+
+    # The node at +path+, or raise SupportDesk::UnknownTopic.
+    def find!(path)
+      find(path) || raise(UnknownTopic, "no topic #{path.inspect} in this desk's tree " \
+                                        "(known: #{@index.keys.sort.join(", ")})")
+    end
+
+    # Whether the tree has a node at +path+.
+    def include?(path) = !find(path).nil?
+
+    # Every node a ticket can actually be filed under.
+    def leaves = select(&:leaf?)
+
+    # A desk with no topics at all: every ticket lands free-form.
+    def empty? = @roots.empty?
+
+    # How many nodes, branches included.
+    def size = count
+
+    # The nodes a requester may see at a given level: pass nothing for the
+    # top level, a node (or its path) to walk into a branch.
+    def visible_for(requester, under: nil)
+      nodes = under ? Array(find(under.to_s)&.children) : @roots
+      nodes.select { |node| node.visible_for?(requester) }
+    end
+
+    # True when the tree has somewhere to put "something else": a leaf
+    # DECLARED as the way out, with `other` or `free_form: true`.
+    #
+    # Not "any leaf that takes no subject" — a tree can be full of
+    # subject-less topics ("safety", "feedback") and still have no honest
+    # answer to "none of the above", which is the failure this guards.
+    def free_form?
+      !free_form_leaf.nil?
+    end
+
+    # The leaf a ticket lands on when nobody picked a topic.
+    def free_form_leaf
+      candidates = leaves.select { |leaf| leaf.catch_all? && !leaf.retired? }
+      candidates.find { |leaf| leaf.key == OTHER_KEY } || candidates.first
+    end
+
+    # Every `about:` class name mentioned anywhere in the tree — what boot
+    # validation and `doctor` check against the supportable registry.
+    def about_class_names
+      flat_map(&:about_class_names).uniq
+    end
+
+    # Used by the DSL while the tree is being built.
+    def add(node, parent: nil) # :nodoc:
+      parent ? parent.add_child(node) : @roots << node
+      @index[node.path] = node
+      node
+    end
+
+    # Used by `other false` to take the way out back out.
+    def remove(path) # :nodoc:
+      node = @index.delete(path.to_s)
+      return nil unless node
+
+      (node.parent ? node.parent.children : @roots).delete(node)
+      node
+    end
+
+    # Freeze the tree and every node in it: built once, at boot.
+    def freeze! # :nodoc:
+      @roots.each(&:deep_freeze)
+      @roots.freeze
+      @index.freeze
+      freeze
+    end
+
+    # Every path in the tree, in one line.
+    def inspect = "#<SupportDesk::TopicTree #{map(&:path).join(" ")}>"
+
+    # The `topic` / `other` DSL. It runs once, at boot, inside
+    # `config.topics do … end` — no metaprogramming, nothing to grep for
+    # later: every node you can see in the initializer is every node there is.
+    class Builder
+      def initialize(tree, parent: nil)
+        @tree = tree
+        @parent = parent
+      end
+
+      # Declare a node. With a block it's a branch and the block declares its
+      # children; without one it's a leaf. See SupportDesk::Topic for every
+      # option (`about:`, `ask:`, `candidates:`, `subject:`, `prefill:`,
+      # `placeholder:`, `only:`, `priority:`, `route_to:`, `desk:`,
+      # `retired:`, `icon:`, `label:`).
+      def topic(key, **options, &block)
+        validate!(key, options)
+
+        node = Topic.new(key: key, parent: @parent, **normalize(options))
+        @tree.add(node, parent: @parent)
+        Builder.new(@tree, parent: node).instance_eval(&block) if block
+        node
+      end
+
+      # The free-form leaf ("Otra cosa"). `other false` removes it — the gem
+      # warns at boot when a tree ends up without one. A host that wants a
+      # differently named way out declares that leaf `free_form: true`.
+      def other(enabled = true, **options)
+        return @tree.remove(TopicTree::OTHER_KEY.to_s) unless enabled
+
+        topic(TopicTree::OTHER_KEY, subject: :none, free_form: true, **options)
+      end
+
+      private
+
+      KNOWN_OPTIONS = %i[
+        label about ask candidates subject prefill placeholder only priority route_to desk retired icon
+        free_form
+      ].freeze
+
+      def validate!(key, options)
+        unless key.is_a?(Symbol) || key.is_a?(String)
+          raise ConfigurationError, "topic keys must be symbols, got #{key.inspect}"
+        end
+
+        unknown = options.keys - KNOWN_OPTIONS
+        if unknown.any?
+          raise ConfigurationError,
+                "unknown topic option#{"s" if unknown.size > 1} #{unknown.map(&:inspect).join(", ")} " \
+                "on topic #{key.inspect} — known options are #{KNOWN_OPTIONS.map(&:inspect).join(", ")}"
+        end
+
+        if options.key?(:subject) && !Topic::SUBJECT_MODES.include?(options[:subject].to_sym)
+          raise ConfigurationError,
+                "topic #{key.inspect}: subject must be one of #{Topic::SUBJECT_MODES.inspect}, " \
+                "got #{options[:subject].inspect}"
+        end
+
+        if options.key?(:priority) && !Topic::PRIORITIES.key?(options[:priority].to_sym)
+          raise ConfigurationError,
+                "topic #{key.inspect}: priority must be one of #{Topic::PRIORITIES.keys.inspect}, " \
+                "got #{options[:priority].inspect}"
+        end
+
+        %i[candidates only prefill].each do |option|
+          next unless options.key?(option)
+          next if option == :prefill && options[option].is_a?(String)
+          next if options[option].respond_to?(:call)
+
+          raise ConfigurationError,
+                "topic #{key.inspect}: #{option} must respond to #call, got #{options[option].inspect}"
+        end
+      end
+
+      # Store `about:` as class NAMES so the tree survives Zeitwerk reloads
+      # and the initializer can name classes that haven't loaded yet.
+      def normalize(options)
+        options = options.dup
+        if options.key?(:about)
+          options[:about] = Array(options[:about]).map { |klass| klass.is_a?(Class) ? klass.name : klass.to_s }
+        end
+        options
+      end
+    end
+  end
+end

data/lib/support_desk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  VERSION = "0.1.0"
+end