support_desk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 953cadd4b7e15695dd5d17092647e38c5595e4b81bccfc2917b491c428f4d7d6
+  data.tar.gz: 077ca8e707b0789140bd484414645ad1217b210d92d02557d7174fd32617b90b
+SHA512:
+  metadata.gz: f442d5f55ab69f61941fcd0b401e0be726d7ca1b228d68d683b52cc14e795d1f136fadf1915faf0153dca9d33a5f3720f764cacd06f3bab3567af20a36393ba6
+  data.tar.gz: 83cc58116727f3f2aebf62f8b61f4a2617d443b58f7cee8179620e5889532e2f281a6515b6c058f7baed4512a259f06592ff6d8b420b2afcbd12e2ddc1241ad6

data/.rubocop.yml

@@ -0,0 +1,32 @@
+# rubocop-rails-omakase is the house style across the gem ecosystem: Rails'
+# own defaults, which means generated code (migrations, initializers) stays
+# clean in a stock Rails app without us reformatting it.
+inherit_gem:
+  rubocop-rails-omakase: rubocop.yml
+
+# MERGE our excludes with rubocop's defaults (vendor/, node_modules/, …) —
+# a bare Exclude key would REPLACE them.
+inherit_mode:
+  merge:
+    - Exclude
+
+AllCops:
+  TargetRubyVersion: 3.2
+  Exclude:
+    # The dummy host app mirrors GENERATED code (its migration is a copy of
+    # the install template) — don't lint it against the gem's own style.
+    - test/dummy/db/**/*
+    # Generator scratch output. `rake ci` runs the tests before rubocop, so
+    # leaving this in would make the set of linted files depend on whether a
+    # generator test had run — a gate that inspects 109 files on a clean
+    # checkout and 111 after a suite is a gate nobody can reproduce. The
+    # generated console is still linted for real: test/dummy's controller is
+    # a verbatim rendering of the same template, and a test keeps them equal.
+    - test/tmp/**/*
+    # Appraisal-generated Gemfiles.
+    - gemfiles/*
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - support_desk.gemspec # the long-form rubygems description is one line by design

data/.simplecov

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# SimpleCov configuration (auto-loaded by `require "simplecov"`); the suite
+# calls SimpleCov.start from test_helper.rb, so this file stays
+# configuration-only. Coherent with the rest of the gem ecosystem (chats,
+# wallets, moderate, usage_credits, …).
+SimpleCov.configure do
+  # SimpleFormatter for terminal-only output (no HTML generation)
+  formatter SimpleCov::Formatter::SimpleFormatter
+
+  # Don't count code that ISN'T unit-testable by this suite and would only
+  # distort the numbers:
+  #   - the test suite itself;
+  #   - generators + their templates: they run via `rails generate
+  #     support_desk:install` in a real host. The generator classes ARE
+  #     exercised by Rails::Generators::TestCase, but the migration template
+  #     itself is never loaded as Ruby here (the dummy migrates a copy of it);
+  #   - version.rb: a single constant, nothing to cover.
+  if respond_to?(:skip)
+    # SimpleCov 1.x vocabulary.
+    skip "/test/"
+    skip "/lib/generators/"
+    skip "/lib/support_desk/version.rb"
+    cover "lib/**/*.rb"
+  else
+    # Fallback vocabulary for SimpleCov 0.22.
+    add_filter "/test/"
+    add_filter "/lib/generators/"
+    add_filter "/lib/support_desk/version.rb"
+    track_files "lib/**/*.rb"
+  end
+
+  enable_coverage :branch
+
+  # Thresholds sit just under the current floor so the gate catches a real
+  # regression without failing on the existing baseline; raise as it grows.
+  minimum_coverage line: 94, branch: 74
+
+  # Disambiguate parallel test runs
+  command_name "Job #{ENV["TEST_ENV_NUMBER"]}" if ENV["TEST_ENV_NUMBER"]
+end
+
+# Print coverage summary to terminal after tests complete
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+  puts "\n#{"=" * 60}"
+  puts "COVERAGE SUMMARY"
+  puts "=" * 60
+  puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"
+  branch_coverage = SimpleCov.result.coverage_statistics[:branch]&.percent&.round(2) || "N/A"
+  puts "Branch Coverage: #{branch_coverage}%"
+  puts "=" * 60
+end

data/Appraisals

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Test the minimum supported Rails version (matches the gemspec floor).
+# `ActiveRecord.after_all_transactions_commit` — how every event this gem
+# emits gets out only after the transition it describes is durable — is a
+# Rails 7.2 API, which is what sets the floor.
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.0"
+end
+
+appraise "rails-8.0" do
+  gem "rails", "~> 8.0.0"
+end
+
+# Test the latest Rails version — this is the default/main Gemfile anyway.
+appraise "rails-8.1" do
+  gem "rails", "~> 8.1.0"
+end

data/CHANGELOG.md

@@ -0,0 +1,135 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-16
+
+First release: the whole core of a support desk, on top of `chats` 0.2.
+
+### Added
+
+- **Tickets that are conversations.** `SupportDesk::Ticket` is a case with
+  exactly one `Chats::Conversation` behind it. Transitions (`reply!`,
+  `note!`, `assign!`, `hand_off!`, `release!`, `close!`, `reopen!`,
+  `change_topic!`, `attach_subject!`) each take `by:`, run under the
+  ticket's row lock, write one append-only event row, and emit after the
+  transaction commits. Repeating one that already happened returns `self`
+  and writes nothing; one that can't happen from here raises
+  `SupportDesk::InvalidTransition`.
+- **Three macros.** `has_support_tickets` adds exactly four methods to
+  whoever asks for help; `supportable topic: :order` makes a domain record
+  something to ask about, with a working default for every method;
+  `acts_as_support_agent if: :admin?` makes someone able to answer, and
+  adds no verbs — the ticket is the subject of every sentence.
+- **Topics as a tree of value objects.** Defined in code, frozen at boot,
+  stored on the ticket as a stable path (`"billing/invoice"`).
+  `ticket.topic` is a `SupportDesk::Topic`, not a string, and a path no tree
+  knows reads as a null object that still renders.
+- **Assignment as a history.** Who held the case, when, why they stopped,
+  with `ticket.assignee` as the denormalised pointer to the one open row.
+  Reopening gives the case back to whoever handled it.
+- **`awaiting` and the SLA clocks**, maintained by a single subscriber to
+  chats' `:message_created` and idempotent on the message id — so a message
+  typed in the app, mirrored in by email or posted by a bot all move the
+  same clock, and a redelivered event never double-counts.
+- **Reply policies**: `:anyone` (the first agent to answer an unheld ticket
+  takes it; a drop-in on someone else's is recorded), `:take_over`,
+  `:assignee_only`.
+- **`SupportDesk::Wizard`** — the three-step "what do you need help with?"
+  machine as a PORO, so the views are replaceable and a native app or an API
+  can drive the same steps. Subjects travel as signed GlobalIDs and are
+  re-checked against `supportable_by?` anyway.
+- **A requester-facing engine you just mount.** `mount SupportDesk::Engine
+  => "/support"` and the user side is done: their list of cases (open ones
+  as chats rows, closed ones folded away), the three wizard frames at one
+  URL, and a stable `/support/tickets/:id` that redirects into the
+  conversation. Every step is a real URL, so the back gesture, a bookmark
+  and a cold-boot deep link all work; `data-turbo-action="advance"` is what
+  lets them also re-render in place. Limits (`max_open_tickets`,
+  `open_rate_limit`) render a wall with the cases they already have listed
+  on it, never a 500.
+- **`link_to_support(about:, text:, **html)` and `support_unread_badge`.**
+  The door renders nothing for a record that is not supportable or not
+  theirs, so it is safe in shared partials, and leads to the conversation
+  they already have rather than opening a second one.
+- **Two rows on chats’ own screens**, through its view slots: the
+  "¿Necesitas ayuda? Escríbenos" door above the inbox for somebody who has
+  never written (`config.inbox_entry`), and a way out of a case closed on a
+  desk configured `closed_tickets: :locked`.
+- **`SupportDesk.native_path_rules(mount:, title:)`** — the Hotwire Native
+  path-configuration rules for both surfaces, as pushed screens.
+- **`config.authenticate_method`** so the engine runs the host’s own
+  authentication filter, and `rails g support_desk:views` to eject every
+  requester-facing template.
+- **Queues and presenters**
+ — `Queue#counts` in one grouped query, a badge
+  cached 30s per agent, `ContextCard`, `Summary`, `Timeline` and
+  `actions_for(agent)`, all with no view dependency.
+- **The agent console, in three layers** — the query objects above, then a
+  routing concern and a controller concern, then a generator. The generated
+  madmin console and the turnkey `SupportDesk::ConsoleEngine` use nothing
+  the concerns don't expose, which is what makes "bring your own UI" a
+  promise rather than a hope.
+  - `concerns: :support_console` in any route set draws member `reply`,
+    `take`, `assign`, `hand_off`, `release`, `close`, `reopen`, `note` and
+    `change_topic`, plus collection `next`.
+  - `SupportDesk::Console` scopes everything it reaches through
+    `config.visible_desks_for` — the ticket, the queue, the tab counts, the
+    badge and `next`, with `?desk=` able to name only a desk already on that
+    list. A case on a desk you may not work is a **404**; no desks at all is
+    a **403**. It asks `config.authorize_console` before every action (a
+    hook that raises denies, and is reported through `Rails.error`), checks
+    `actions_for` so it never accepts a verb it wouldn't have offered, sets
+    `SupportDesk::Current.actor`, and turns every domain refusal into a
+    translated flash — a policy never 500s.
+    `SupportDesk::Console::Index` is the optional `@queue` / `@scope` /
+    `@tickets`, preloading everything a row renders including the subject.
+  - `rails g support_desk:console madmin` writes a host-owned controller, a
+    madmin resource, and the view set: queue tabs, waiting chips coloured by
+    `at_risk_after` / `reply_within`, context card, transcript, timeline,
+    a "Reply"/"Internal note" composer, the hand-off picker, and a nav badge.
+    Idempotent, `--force` to take new defaults.
+  - `mount SupportDesk::ConsoleEngine => "/admin/support"` for hosts with no
+    admin framework, rendering those same views through
+    `config.console_parent_controller`.
+- **Events out, policy in.** `SupportDesk.on(:ticket_opened) { … }`,
+  multi-subscriber, isolated with `Rails.error.report`, mirrored on
+  `ActiveSupport::Notifications`.
+- **Multi-desk configuration** where every desk inherits what it doesn't
+  state, with setters that validate on assignment and boot-time
+  `ConfigurationError`s that carry the fix. `config.visible_desks_for` and
+  `config.authorize_console` are the console's two hooks into it.
+- **`SupportDesk.doctor`** — configuration, the chats seams, and the data
+  invariants, with an `ok?` for CI.
+- **`SupportDesk::TestHelpers`** for host suites.
+- Install generator (migration + annotated initializer), Spanish and
+  English locales, and a mountable engine.
+
+### Notes
+
+- **The desk registers itself with chats at boot.** `acts_as_messager`
+  registers a class when it loads, and `Chats::Inbox` folds support threads
+  into one row only for registered grouped messagers, so under lazy
+  autoloading the inbox showed every support conversation as its own row
+  until something happened to reference `SupportDesk::Desk`. The engine's
+  `to_prepare` now touches the desk the way it already touches the helper
+  (#2). Eager-loading production hosts never saw it; development did.
+- **`jsonb` on PostGIS.** The install migration decides jsonb-or-json by
+  adapter name, and activerecord-postgis-adapter answers `"PostGIS"`, not
+  `"PostgreSQL"` — the first cut matched the full word and silently gave
+  PostGIS hosts plain `json` columns. Caught while integrating with a PostGIS host, before
+  the gem shipped; the template now matches the prefix (`/\Apostg/i`).
+- `SupportDesk::OffDuty` is NOT part of 0.1.0. Duty is a seam this release
+  only asks about (`agent.on_duty?` decides who is notified and what
+  `actions_for` offers); nothing in it assigns work, so nothing can
+  honestly refuse on those grounds yet. It arrives with the duty table in
+  0.3. `SupportDesk::Locked` IS raised — writing into a closed ticket on a
+  desk configured `closed_tickets: :locked` — and subclasses
+  `InvalidTransition`, so either name catches it.
+
+### Credits
+
+The wizard copy, the console screens and the Spanish strings began life in
+carhey#309, and were lifted into the gem with the author's blessing.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Javi R
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.