support_desk 0.1.3 → 0.2.0

data/config/locales/support_desk.es.yml

@@ -8,6 +8,11 @@ es:
       closed_notice: "Esta conversación está cerrada. Abre una nueva si necesitas algo más."
       reopened_notice: "Hemos vuelto a abrir esta conversación."
       promise: "Normalmente respondemos en menos de %{time}"
+      # La línea con la que se abre un hilo que ha empezado el equipo: quien
+      # recibe un mensaje de un sitio al que nunca ha escrito necesita saber
+      # qué es esto.
+      opened_by_support: "%{desk} ha abierto esta conversación contigo sobre «%{label}». Puedes responder aquí mismo."
+      unavailable_notice: "Esta cuenta ya no puede enviar ni recibir mensajes. La conversación se queda aquí para consultarla."
     notifications:
       # Generic on purpose: una pantalla de bloqueo no debe contar de qué va
       # el caso de nadie. El detalle va en el cuerpo.
@@ -45,6 +50,7 @@ es:
       state:
         awaiting_reply: "Estamos con ello"
         answered: "Te hemos contestado"
+        opened_by_support: "Te hemos escrito"
         closed: "Cerrada"
     # The ways in, from anywhere in the host app.
     doors:

data/lib/generators/support_desk/console_generator.rb

@@ -60,7 +60,7 @@ module SupportDesk
         say "  1. One route line:"
         say "       # config/routes.rb"
         say "       namespace :#{target} do"
-        say "         resources :support_tickets, only: %i[index show], concerns: :support_console"
+        say "         resources :support_tickets, only: %i[index show new], concerns: :support_console"
         say "       end"
 
         say "  2. A badge in your admin nav:"

data/lib/generators/support_desk/install_generator.rb

@@ -27,6 +27,15 @@ module SupportDesk
                            File.join(db_migrate_path, "create_support_desk_tables.rb")
       end
 
+      # Who opened each case. A SEPARATE migration, copied from the same
+      # template `support_desk:upgrade` hands an existing install, so one
+      # file owns those two columns and their index wherever they came from
+      # — and a fresh install's `down` removes exactly what its `up` added.
+      def create_opened_by_migration
+        migration_template "add_opened_by_to_support_desk_tickets.rb.erb",
+                           File.join(db_migrate_path, "add_opened_by_to_support_desk_tickets.rb")
+      end
+
       # The annotated initializer — every setting the gem has, with what it
       # means and what it defaults to.
       def create_initializer
@@ -72,6 +81,11 @@ module SupportDesk
         say "  # app/mailboxes/application_mailbox.rb"
         say "  #   routing(/^support@/i => :support_desk)"
 
+        say "\n  Already installed and bumping the version? 'rails g support_desk:upgrade' copies"
+        say "  only the migrations the new version needs (0.2.0: who opened the case), and"
+        say "  nothing you own. Follow the CHANGELOG's drained cutover: migrate, pause"
+        say "  support traffic, drain old web/workers, backfill, then serve only 0.2."
+
         say "\nCheck your work any time with SupportDesk.doctor.print"
         say "You now have support tickets that are real conversations. 🚀\n", :green
       end

data/lib/generators/support_desk/templates/add_opened_by_to_support_desk_tickets.rb.erb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# support_desk 0.2.0 — WHO OPENED THE CASE.
+#
+# `opened_by` is a record, exactly like `closed_by`: the requester when they
+# asked, the agent when the desk wrote first. It is nullable for one reason
+# only — rows written by 0.1.x have no provenance to state — and this
+# migration backfills every one of them to its requester, because 0.1 had no
+# way to open a case as anybody else.
+#
+# The new column's type is read from the tickets table's OWN `requester_id`
+# rather than from today's generator setting: both columns point at the same
+# host records, so an app that changed `primary_key_type` after installing
+# would otherwise be handed a bigint column for uuid ids.
+class AddOpenedByToSupportDeskTickets < ActiveRecord::Migration<%= migration_version %>
+  INDEX_NAME = "index_support_desk_tickets_on_opened_by"
+
+  def up
+    ensure_columns_are_ours!
+
+    add_reference :support_desk_tickets, :opened_by, polymorphic: true, null: true,
+                                                     type: opened_by_id_type, index: false
+    add_index :support_desk_tickets, [ :opened_by_type, :opened_by_id ], name: INDEX_NAME
+
+    # SQL, and deliberately not the model: a backfill that loaded today's
+    # Ticket would run this release's validations, callbacks and events over
+    # last release's rows, in a migration that must only move two columns.
+    execute(<<~SQL.squish)
+      UPDATE support_desk_tickets
+         SET opened_by_type = requester_type,
+             opened_by_id = requester_id
+       WHERE opened_by_id IS NULL
+    SQL
+  end
+
+  # Exactly what `up` added, and nothing else. Note that this DESTROYS
+  # provenance: every case the desk opened stops being distinguishable from
+  # one the requester opened. It is here for a failed deploy of the schema
+  # alone, never as the way back from a code rollback.
+  def down
+    remove_index :support_desk_tickets, name: INDEX_NAME if
+      index_exists?(:support_desk_tickets, [ :opened_by_type, :opened_by_id ], name: INDEX_NAME)
+
+    remove_column :support_desk_tickets, :opened_by_type if
+      column_exists?(:support_desk_tickets, :opened_by_type)
+    remove_column :support_desk_tickets, :opened_by_id if
+      column_exists?(:support_desk_tickets, :opened_by_id)
+  end
+
+  private
+
+  # A column we did not add is a schema we cannot reason about: its type may
+  # not match, it may hold something else's data, and `down` would drop it.
+  # Say so with the way out rather than skipping the backfill and the index
+  # in silence.
+  def ensure_columns_are_ours!
+    existing = %i[opened_by_type opened_by_id].select { |name| column_exists?(:support_desk_tickets, name) }
+    return if existing.empty?
+
+    raise ActiveRecord::MigrationError,
+          "support_desk_tickets already has #{existing.join(" and ")}. This migration owns those two columns " \
+          "and #{INDEX_NAME}, so it won't overwrite them. Verify both column types, the index and existing " \
+          "provenance against this migration before reconciling its version in schema_migrations. " \
+          "db:migrate:up runs this method again; it does not mark it as already run. Preserve existing data."
+  end
+
+  # The storage this table already uses for a host record's id — uuid,
+  # bigint, integer. `opened_by_id` points at the same records as
+  # `requester_id`, so it has to be stored the same way.
+  def opened_by_id_type
+    column = connection.columns(:support_desk_tickets).find { |candidate| candidate.name == "requester_id" }
+    unless column
+      raise ActiveRecord::MigrationError,
+            "support_desk_tickets has no requester_id column — run support_desk's install migration first."
+    end
+
+    column.sql_type
+  end
+end

data/lib/generators/support_desk/templates/console/controller.rb.erb

@@ -16,7 +16,7 @@ module <%= module_name %>
   # The routes come from the `:support_console` routing concern:
   #
   #   namespace :<%= target %> do
-  #     resources :support_tickets, only: %i[index show], concerns: :support_console
+  #     resources :support_tickets, only: %i[index show new], concerns: :support_console
   #   end
   #
   # Both `index` and `show` are yours — the gem deliberately doesn't own the

data/lib/generators/support_desk/templates/initializer.rb

@@ -19,6 +19,23 @@ SupportDesk.configure do |config|
   #
   # config.agents { User.where(admin: true) }
 
+  # Who may ask, and who may answer, record by record — the macros' `if:`:
+  #
+  #   class User < ApplicationRecord
+  #     has_support_tickets if: :kept?          # a closed account can neither
+  #     acts_as_support_agent if: :admin?       # ask nor be written to
+  #   end
+  #
+  # `has_support_tickets if:` is a WRITE rule, not a screen rule: the thread
+  # and its history stay readable when it turns false.
+
+  # How the console finds the person an agent types in "Write to someone":
+  # email, phone, handle — your call. Given the typed string, return a
+  # requester record or nil. Without it the console accepts only a GlobalID
+  # from one of your own pages.
+  #
+  # config.find_requester { |query| User.find_by(email: query.to_s.strip.downcase) }
+
   # ==========================================================================
   # CONTROLLER INTEGRATION
   # ==========================================================================
@@ -105,6 +122,19 @@ SupportDesk.configure do |config|
   #
   # config.announce_assignments = :first_only
   #
+  # The system line a thread opens with, posted inside the opening
+  # transaction and before the first message. A String with %{label},
+  # %{desk} and %{reply_within}, a Symbol naming an I18n key, a block given
+  # the ticket, or nil for no line at all.
+  #
+  # The second one is for a case the DESK opened
+  # (`lucia.open_support_conversation_with!(alice, "Vimos que…")`): it has a
+  # default, because a message from a desk somebody never wrote to has to
+  # explain itself.
+  #
+  # config.opening_line = "Has abierto una conversación sobre «%{label}». Te contestamos aquí."
+  # config.opening_line_from_support = "%{desk} ha abierto esta conversación contigo sobre «%{label}»."
+  #
   # What a requester writing into a closed ticket does:
   #   :reopen_on_reply  the case comes back (no wall, no dead end)
   #   :locked           the composer is replaced by a notice

data/lib/generators/support_desk/upgrade_generator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module SupportDesk
+  module Generators
+    # `rails generate support_desk:upgrade` — copy the migrations a version
+    # bump needs into an EXISTING install. Nothing else: the initializer, the
+    # views, the console and the routes you already own stay untouched.
+    #
+    # Currently writes the 0.2.0 migration (who opened the case), which is the
+    # SAME template a fresh install runs — one file owns those columns, so a
+    # fresh install and an upgraded one end up with the same schema and the
+    # same rollback. Running this twice writes nothing the second time: the
+    # migration already sitting in db/migrate is identical, and Rails skips it.
+    class UpgradeGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Add the migrations a support_desk version bump needs (0.2.0: opened_by)"
+
+      # Rails' migration numbering, borrowed from ActiveRecord's generators.
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_opened_by_migration
+        migration_template "add_opened_by_to_support_desk_tickets.rb.erb",
+                           File.join(db_migrate_path, "add_opened_by_to_support_desk_tickets.rb")
+      end
+
+      def display_post_upgrade_message
+        say "\n🎫 support_desk upgrade migrations copied.", :green
+        say "\n  1. Run 'rails db:migrate'. It adds `opened_by` and points every existing"
+        say "     case at its requester — 0.1 had no other way to open one."
+        say "  2. New in 0.2.0:"
+        say "       lucia.open_support_conversation_with!(alice, \"Vimos que…\")   # the desk writes first"
+        say "       ticket.opened_by / opened_by_support? / opened_by_requester?"
+        say "       config.opening_line / config.opening_line_from_support / config.find_requester"
+        say "       has_support_tickets if: :kept?                                 # who may be written to"
+        say "  3. Migrate BEFORE 0.2 serves traffic. Pause support writes; stop and drain"
+        say "     ALL old web requests and workers. This is NOT a rolling deployment."
+        say "     Keep traffic paused, run 'rake support_desk:backfill_opened_by' under 0.2,"
+        say "     verify no NULL openers remain, then start only 0.2 and resume traffic."
+        say "  4. See the CHANGELOG for the full list.\n", :green
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/support_desk/configuration.rb

@@ -50,10 +50,21 @@ module SupportDesk
       # fails at boot instead of silently leaving tickets unassigned.
       UNRELEASED_ROUTING_STRATEGIES = %i[round_robin least_loaded].freeze
 
+      # The sample a static opening line is interpolated against the moment it
+      # is assigned, so a typo'd %{labe} is a boot failure and not a 3am
+      # exception in the middle of somebody opening a case.
+      LINE_INTERPOLATIONS = { label: "…", desk: "…", reply_within: "…" }.freeze
+
       DEFAULTS = {
         name: nil,
         avatar: nil,
         email: nil,
+        opening_line: nil,
+        # A message from a desk you never wrote to has to explain itself, so
+        # this one has a default and `opening_line` does not: existing hosts'
+        # threads keep opening exactly as they do today.
+        opening_line_from_support: :"support_desk.thread.opened_by_support",
+        find_requester: nil,
         reply_policy: :anyone,
         announce_assignments: :first_only,
         closed_tickets: :reopen_on_reply,
@@ -116,6 +127,109 @@ module SupportDesk
         @settings[:email] = value&.to_s
       end
 
+      # --- What a thread opens with ---------------------------------------------
+
+      # The system line every thread opens with, posted INSIDE the opening
+      # transaction and before the first message, so it can never arrive
+      # after the message it introduces (or not at all).
+      #
+      # A String with %{label}, %{desk} and %{reply_within}; a Symbol naming
+      # an I18n key that takes the same interpolations; a block given the
+      # ticket; or nil for no line at all, which is the default.
+      #
+      #   config.opening_line = "Has abierto una conversación sobre «%{label}»."
+      #   config.opening_line { |ticket| ticket.subject ? … : … }
+      def opening_line(&block)
+        return @settings[:opening_line] = block if block
+
+        read(:opening_line)
+      end
+
+      # Set it, validating on assignment (see the reader above).
+      def opening_line=(value)
+        @settings[:opening_line] = ensure_line(value, "opening_line")
+      end
+
+      # The same line for a case the DESK opened. Defaults to the gem's own
+      # I18n key, because somebody who never wrote to you needs to be told
+      # what this is.
+      def opening_line_from_support(&block)
+        return @settings[:opening_line_from_support] = block if block
+
+        read(:opening_line_from_support)
+      end
+
+      # Set it, validating on assignment (see the reader above).
+      def opening_line_from_support=(value)
+        @settings[:opening_line_from_support] = ensure_line(value, "opening_line_from_support")
+      end
+
+      # How a console finds the person an agent types: email, phone, handle,
+      # whatever this host lets staff search by. Given the typed string,
+      # returns a requester record or nil.
+      #
+      #   config.find_requester { |query| User.find_by(email: query.to_s.strip.downcase) }
+      #
+      # nil (the default) means the console accepts only a GlobalID from one
+      # of your own pages. Multi-tenant hosts scope BOTH ways in — this hook
+      # is a lookup, never an authorization.
+      def find_requester(&block)
+        return @settings[:find_requester] = block if block
+
+        read(:find_requester)
+      end
+
+      # Set it, validating on assignment (see the reader above).
+      def find_requester=(value)
+        @settings[:find_requester] = value.nil? ? nil : ensure_callable(value, "find_requester")
+      end
+
+      # What's wrong with this desk's opening lines, as sentences — what
+      # `doctor` reports. A String is interpolated against the sample, a
+      # Symbol has to exist in the current locale, and a block is left alone:
+      # it needs a ticket, and running a host's callback as a diagnostic is
+      # not a diagnostic.
+      def opening_line_problems # :nodoc:
+        %i[opening_line opening_line_from_support].filter_map do |setting|
+          value = public_send(setting)
+          next if value.nil? || value.respond_to?(:call)
+
+          if value.is_a?(Symbol)
+            next if I18n.exists?(value)
+
+            "#{setting} names #{value.inspect}, which has no #{I18n.locale} translation"
+          else
+            begin
+              interpolate_line(value, LINE_INTERPOLATIONS, setting.to_s)
+              nil
+            rescue ConfigurationError => e
+              e.message
+            end
+          end
+        end
+      end
+
+      # What to post for THIS ticket, resolved and interpolated in the
+      # current locale. nil or blank means post nothing.
+      def opening_line_for(ticket)
+        setting = ticket.opened_by_support? ? opening_line_from_support : opening_line
+        return nil if setting.nil?
+
+        line = case setting
+        when Symbol then I18n.t(setting, **line_interpolations(ticket), raise: true)
+        when String then interpolate_line(setting, line_interpolations(ticket), "opening_line")
+        else setting.call(ticket)
+        end
+        return nil if line.nil?
+
+        unless line.is_a?(String)
+          raise ConfigurationError,
+                "an opening_line block must return a String or nil, got #{line.inspect}"
+        end
+
+        line
+      end
+
       # --- Who answers ----------------------------------------------------------
 
       # The agent pool: notified while a ticket is unassigned, offered in the
@@ -372,14 +486,46 @@ module SupportDesk
 
         value
       end
+
+      # nil, a String, an I18n key, or something to call. A String is
+      # interpolated here and now against the sample, so an unknown
+      # placeholder fails at boot rather than inside a transaction.
+      def ensure_line(value, name)
+        return value if value.nil? || value.is_a?(Symbol) || value.respond_to?(:call)
+        if value.is_a?(String)
+          interpolate_line(value, LINE_INTERPOLATIONS, name)
+          return value
+        end
+
+        raise ConfigurationError,
+              "#{name} must be a String, an I18n key (Symbol), a block, or nil, got #{value.inspect}"
+      end
+
+      # Named interpolation, NOT String#%: "100% ready" is ordinary copy in
+      # any language, and `%` would read that as a format directive and
+      # raise. I18n.interpolate leaves a literal percent alone and only
+      # touches %{named} placeholders.
+      def interpolate_line(line, interpolations, name)
+        I18n.interpolate(line, interpolations)
+      rescue KeyError, ArgumentError => e
+        raise ConfigurationError,
+              "#{name} can't be interpolated (#{e.class}: #{e.message}). The placeholders it can use are " \
+              "#{LINE_INTERPOLATIONS.keys.map { |key| "%{#{key}}" }.join(", ")}."
+      end
+
+      def line_interpolations(ticket)
+        { label: ticket.label, desk: ticket.desk.name,
+          reply_within: (SupportDesk.humanize_duration(reply_within) if reply_within) }
+      end
     end
 
     # Settings that belong to a desk rather than the installation. The
     # top-level accessors forward to the `:default` desk, which is also what
     # every other desk falls back to.
     DESK_SETTINGS = %i[
-      name avatar email reply_policy announce_assignments closed_tickets reply_within at_risk_after
-      open_rate_limit max_open_tickets inbox_entry routing mirror_replies_by_email auto_close_after
+      name avatar email opening_line opening_line_from_support find_requester reply_policy
+      announce_assignments closed_tickets reply_within at_risk_after open_rate_limit max_open_tickets
+      inbox_entry routing mirror_replies_by_email auto_close_after
     ].freeze
 
     delegate(*DESK_SETTINGS, *DESK_SETTINGS.map { |setting| :"#{setting}=" }, to: :default_desk)