escalated 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b01fcbc99a3f41dca9db58cd8bd8d03037d63aa6cc7e308f8b482bc9b555aa79
+  data.tar.gz: 66dd31da20521e8e20cfcbdf86b0ea349d2c794d2660c8ba2a56ede336cc7fdc
+SHA512:
+  metadata.gz: 48df414672dc4b1ed5e50ffebc6c0ad3fa5ffce96f98244ab7667cc87a2861e815499daa3db7bc229df6634d95a89953daaf79039951b3bc23b182c832edb236
+  data.tar.gz: e0b2c2c4adbdac476e4abd16ea84a872bf8eea70ead4427f285ff622f7c837fb24c1cbac7e32543e1ca30d8465fa01cb468bf8373d98ef0e77f22a522d418dbe

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Escalated Dev
+
+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.

data/README.md

@@ -0,0 +1,302 @@
+# Escalated for Rails
+
+A full-featured, embeddable support ticket system for Rails. Drop it into any app — get a complete helpdesk with SLA tracking, escalation rules, agent workflows, and a customer portal. No external services required.
+
+**Three hosting modes.** Run entirely self-hosted, sync to a central cloud for multi-app visibility, or proxy everything to the cloud. Switch modes with a single config change.
+
+## Features
+
+- **Ticket lifecycle** — Create, assign, reply, resolve, close, reopen with configurable status transitions
+- **SLA engine** — Per-priority response and resolution targets, business hours calculation, automatic breach detection
+- **Escalation rules** — Condition-based rules that auto-escalate, reprioritize, reassign, or notify
+- **Agent dashboard** — Ticket queue with filters, bulk actions, internal notes, canned responses
+- **Customer portal** — Self-service ticket creation, replies, and status tracking
+- **Admin panel** — Manage departments, SLA policies, escalation rules, tags, and view reports
+- **File attachments** — Drag-and-drop uploads with configurable storage and size limits
+- **Activity timeline** — Full audit log of every action on every ticket
+- **Email notifications** — Configurable per-event notifications with webhook support
+- **Department routing** — Organize agents into departments with auto-assignment (round-robin)
+- **Tagging system** — Categorize tickets with colored tags
+- **Inertia.js + Vue 3 UI** — Shared frontend via [`@escalated-dev/escalated`](https://github.com/escalated-dev/escalated)
+
+### v0.4.0 — Advanced Features
+
+- **Bulk actions** — Assign, change status/priority, add tags, close, or delete multiple tickets at once
+- **Macros** — Reusable multi-step automations (set status + assign + add note in one click)
+- **Ticket followers** — Agents follow tickets and receive the same notifications as the assignee
+- **Satisfaction ratings** — 1-5 star CSAT ratings with optional comments after resolution
+- **Pinned notes** — Pin important internal notes to the top of the ticket thread
+- **Keyboard shortcuts** — Full keyboard navigation for power users
+- **Quick filters** — One-click filter chips (My Tickets, Unassigned, Urgent, SLA Breaching)
+- **Presence indicators** — See who else is viewing a ticket in real-time
+- **Enhanced dashboard** — CSAT metrics, resolution times, SLA breach tracking
+
+## Requirements
+
+- Ruby 3.1+
+- Rails 7.1+
+- Node.js 18+ (for frontend assets)
+
+## Quick Start
+
+```bash
+bundle add escalated
+npm install @escalated-dev/escalated
+rails generate escalated:install
+rails db:migrate
+```
+
+Add the `Ticketable` concern to your User model:
+
+```ruby
+class User < ApplicationRecord
+  include Escalated::Ticketable
+end
+```
+
+Define authorization in your `ApplicationController` or an initializer:
+
+```ruby
+# config/initializers/escalated.rb
+Escalated.configure do |config|
+  config.admin_check = ->(user) { user.admin? }
+  config.agent_check = ->(user) { user.agent? || user.admin? }
+end
+```
+
+Visit `/support` — you're live.
+
+## Frontend Setup
+
+Escalated uses Inertia.js with Vue 3. The frontend components are provided by the [`@escalated-dev/escalated`](https://github.com/escalated-dev/escalated) npm package.
+
+### Tailwind Content
+
+Add the Escalated package to your Tailwind `content` config so its classes aren't purged:
+
+```js
+// tailwind.config.js
+content: [
+    // ... your existing paths
+    './node_modules/@escalated-dev/escalated/src/**/*.vue',
+],
+```
+
+### Page Resolver
+
+Add the Escalated pages to your Inertia page resolver:
+
+```javascript
+// app/javascript/entrypoints/application.js
+import { createApp, h } from 'vue'
+import { createInertiaApp } from '@inertiajs/vue3'
+
+createInertiaApp({
+  resolve: name => {
+    if (name.startsWith('Escalated/')) {
+      const escalatedPages = import.meta.glob(
+        '../../../node_modules/@escalated-dev/escalated/src/pages/**/*.vue',
+        { eager: true }
+      )
+      const pageName = name.replace('Escalated/', '')
+      return escalatedPages[`../../../node_modules/@escalated-dev/escalated/src/pages/${pageName}.vue`]
+    }
+
+    const pages = import.meta.glob('../pages/**/*.vue', { eager: true })
+    return pages[`../pages/${name}.vue`]
+  },
+  setup({ el, App, props, plugin }) {
+    createApp({ render: () => h(App, props) })
+      .use(plugin)
+      .mount(el)
+  },
+})
+```
+
+### Theming (Optional)
+
+Register the `EscalatedPlugin` to render Escalated pages inside your app's layout — no page duplication needed:
+
+```javascript
+import { EscalatedPlugin } from '@escalated-dev/escalated'
+import AppLayout from '@/layouts/AppLayout.vue'
+
+createInertiaApp({
+  setup({ el, App, props, plugin }) {
+    createApp({ render: () => h(App, props) })
+      .use(plugin)
+      .use(EscalatedPlugin, {
+        layout: AppLayout,
+        theme: {
+          primary: '#3b82f6',
+          radius: '0.75rem',
+        }
+      })
+      .mount(el)
+  },
+})
+```
+
+Your layout component must accept a `#header` slot and a default slot. Escalated will render its sub-navigation in the header and page content in the default slot. Without the plugin, Escalated uses its own standalone layout.
+
+See the [`@escalated-dev/escalated` README](https://github.com/escalated-dev/escalated) for full theming documentation and CSS custom properties.
+
+## Hosting Modes
+
+### Self-Hosted (default)
+
+Everything stays in your database. No external calls. Full autonomy.
+
+```ruby
+Escalated.configure do |config|
+  config.mode = :self_hosted
+end
+```
+
+### Synced
+
+Local database + automatic sync to `cloud.escalated.dev` for unified inbox across multiple apps. If the cloud is unreachable, your app keeps working — events queue and retry.
+
+```ruby
+Escalated.configure do |config|
+  config.mode = :synced
+  config.hosted_api_url = "https://cloud.escalated.dev/api/v1"
+  config.hosted_api_key = ENV["ESCALATED_API_KEY"]
+end
+```
+
+### Cloud
+
+All ticket data proxied to the cloud API. Your app handles auth and renders UI, but storage lives in the cloud.
+
+```ruby
+Escalated.configure do |config|
+  config.mode = :cloud
+  config.hosted_api_url = "https://cloud.escalated.dev/api/v1"
+  config.hosted_api_key = ENV["ESCALATED_API_KEY"]
+end
+```
+
+All three modes share the same controllers, UI, and business logic. The driver pattern handles the rest.
+
+## Configuration
+
+Create or edit `config/initializers/escalated.rb`:
+
+```ruby
+Escalated.configure do |config|
+  config.mode = :self_hosted
+  config.user_class = "User"
+  config.table_prefix = "escalated_"
+  config.route_prefix = "support"
+  config.default_priority = :medium
+
+  # Middleware
+  config.middleware = [:authenticate_user!]
+  config.admin_middleware = nil
+
+  # Tickets
+  config.allow_customer_close = true
+  config.auto_close_resolved_after_days = 7
+  config.max_attachments_per_reply = 5
+  config.max_attachment_size_kb = 10240
+
+  # SLA
+  config.sla = {
+    enabled: true,
+    business_hours_only: true,
+    business_hours: {
+      start: 9, end: 17,
+      timezone: "UTC",
+      working_days: [1, 2, 3, 4, 5]
+    }
+  }
+
+  # Notifications
+  config.notification_channels = [:email]
+  config.webhook_url = nil
+
+  # Storage (ActiveStorage)
+  config.storage_service = :local
+end
+```
+
+## Scheduling
+
+Add these to your scheduler for SLA and escalation automation:
+
+```ruby
+# config/schedule.rb (whenever gem) or use solid_queue/sidekiq-cron
+every 1.minute do
+  runner "Escalated::CheckSlaJob.perform_now"
+end
+
+every 5.minutes do
+  runner "Escalated::EvaluateEscalationsJob.perform_now"
+end
+
+every 1.day do
+  runner "Escalated::CloseResolvedJob.perform_now"
+end
+
+every 1.week do
+  runner "Escalated::PurgeActivitiesJob.perform_now"
+end
+```
+
+## Routes
+
+Routes are automatically mounted when the engine loads. By default they mount at `/support`.
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/support` | GET | Customer ticket list |
+| `/support/create` | GET | New ticket form |
+| `/support/{ticket}` | GET | Ticket detail |
+| `/support/agent` | GET | Agent dashboard |
+| `/support/agent/tickets` | GET | Agent ticket queue |
+| `/support/agent/tickets/{ticket}` | GET | Agent ticket view |
+| `/support/admin/reports` | GET | Admin reports |
+| `/support/admin/departments` | GET | Department management |
+| `/support/admin/sla-policies` | GET | SLA policy management |
+| `/support/admin/escalation-rules` | GET | Escalation rule management |
+| `/support/admin/tags` | GET | Tag management |
+| `/support/admin/canned-responses` | GET | Canned response management |
+| `/support/agent/tickets/bulk` | POST | Bulk actions on multiple tickets |
+| `/support/agent/tickets/{ticket}/follow` | POST | Follow/unfollow a ticket |
+| `/support/agent/tickets/{ticket}/macro` | POST | Apply a macro to a ticket |
+| `/support/agent/tickets/{ticket}/presence` | POST | Update presence on a ticket |
+| `/support/agent/tickets/{ticket}/pin/{reply}` | POST | Pin/unpin an internal note |
+| `/support/{ticket}/rate` | POST | Submit satisfaction rating |
+
+## Events
+
+Connect to ticket lifecycle events via ActiveSupport::Notifications:
+
+```ruby
+ActiveSupport::Notifications.subscribe("escalated.ticket_created") do |event|
+  ticket = event.payload[:ticket]
+  # Handle new ticket
+end
+```
+
+## Also Available For
+
+- **[Escalated for Laravel](https://github.com/escalated-dev/escalated-laravel)** — Laravel Composer package
+- **[Escalated for Rails](https://github.com/escalated-dev/escalated-rails)** — Ruby on Rails engine (you are here)
+- **[Escalated for Django](https://github.com/escalated-dev/escalated-django)** — Django reusable app
+- **[Escalated for AdonisJS](https://github.com/escalated-dev/escalated-adonis)** — AdonisJS v6 package
+- **[Escalated for Filament](https://github.com/escalated-dev/escalated-filament)** — Filament v3 admin panel plugin
+- **[Shared Frontend](https://github.com/escalated-dev/escalated)** — Vue 3 + Inertia.js UI components
+
+Same architecture, same Vue UI, same three hosting modes — for every major backend framework.
+
+## Testing
+
+```bash
+bundle exec rspec
+```
+
+## License
+
+MIT

data/app/controllers/escalated/admin/bulk_actions_controller.rb

@@ -0,0 +1,42 @@
+module Escalated
+  module Admin
+    class BulkActionsController < Escalated::ApplicationController
+      before_action :require_admin!
+
+      def create
+        ticket_ids = params[:ticket_ids]
+        action = params[:action]
+        value = params[:value]
+        success_count = 0
+
+        tickets = Escalated::Ticket.where(id: ticket_ids)
+
+        tickets.each do |ticket|
+          begin
+            case action.to_s
+            when "status"
+              Services::TicketService.transition_status(ticket, value, actor: escalated_current_user)
+            when "priority"
+              Services::TicketService.change_priority(ticket, value, actor: escalated_current_user)
+            when "assign"
+              agent = Escalated.configuration.user_model.find(value)
+              Services::AssignmentService.assign(ticket, agent, actor: escalated_current_user)
+            when "tag"
+              Services::TicketService.add_tags(ticket, Array(value), actor: escalated_current_user)
+            when "close"
+              Services::TicketService.close(ticket, actor: escalated_current_user)
+            when "delete"
+              ticket.destroy!
+            end
+            success_count += 1
+          rescue StandardError => e
+            Rails.logger.warn("[Escalated::BulkActions] Failed to #{action} ticket ##{ticket.id}: #{e.message}")
+          end
+        end
+
+        redirect_back fallback_location: escalated.admin_tickets_path,
+                      notice: "#{success_count} ticket(s) updated."
+      end
+    end
+  end
+end

data/app/controllers/escalated/admin/canned_responses_controller.rb

@@ -0,0 +1,73 @@
+module Escalated
+  module Admin
+    class CannedResponsesController < Escalated::ApplicationController
+      before_action :require_admin!
+      before_action :set_canned_response, only: [:update, :destroy]
+
+      def index
+        responses = Escalated::CannedResponse.ordered
+
+        render inertia: "Escalated/Admin/CannedResponses/Index", props: {
+          canned_responses: responses.map { |r| canned_response_json(r) }
+        }
+      end
+
+      def create
+        response = Escalated::CannedResponse.new(canned_response_params)
+        response.created_by = escalated_current_user.id
+
+        if response.save
+          redirect_to admin_canned_responses_path, notice: "Canned response created."
+        else
+          redirect_back fallback_location: admin_canned_responses_path,
+                        alert: response.errors.full_messages.join(", ")
+        end
+      end
+
+      def update
+        if @canned_response.update(canned_response_params)
+          redirect_to admin_canned_responses_path, notice: "Canned response updated."
+        else
+          redirect_back fallback_location: admin_canned_responses_path,
+                        alert: @canned_response.errors.full_messages.join(", ")
+        end
+      end
+
+      def destroy
+        @canned_response.destroy!
+        redirect_to admin_canned_responses_path, notice: "Canned response deleted."
+      end
+
+      private
+
+      def set_canned_response
+        @canned_response = Escalated::CannedResponse.find(params[:id])
+      end
+
+      def canned_response_params
+        params.require(:canned_response).permit(:title, :body, :shortcode, :category, :is_shared)
+      end
+
+      def canned_response_json(response)
+        {
+          id: response.id,
+          title: response.title,
+          body: response.body,
+          shortcode: response.shortcode,
+          category: response.category,
+          is_shared: response.is_shared,
+          creator: response.creator ? {
+            id: response.creator.id,
+            name: response.creator.respond_to?(:name) ? response.creator.name : response.creator.email
+          } : nil,
+          created_at: response.created_at&.iso8601,
+          updated_at: response.updated_at&.iso8601
+        }
+      end
+
+      def admin_canned_responses_path
+        escalated.admin_canned_responses_path
+      end
+    end
+  end
+end

data/app/controllers/escalated/admin/departments_controller.rb

@@ -0,0 +1,135 @@
+module Escalated
+  module Admin
+    class DepartmentsController < Escalated::ApplicationController
+      before_action :require_admin!
+      before_action :set_department, only: [:show, :edit, :update, :destroy]
+
+      def index
+        departments = Escalated::Department.ordered
+
+        render inertia: "Escalated/Admin/Departments/Index", props: {
+          departments: departments.map { |d| department_json(d) }
+        }
+      end
+
+      def new
+        render inertia: "Escalated/Admin/Departments/Form", props: {
+          department: nil,
+          sla_policies: Escalated::SlaPolicy.active.ordered.map { |p| { id: p.id, name: p.name } },
+          agents: agent_list
+        }
+      end
+
+      def create
+        department = Escalated::Department.new(department_params)
+
+        if department.save
+          sync_agents(department, params[:agent_ids])
+          redirect_to admin_department_path(department), notice: "Department created."
+        else
+          redirect_back fallback_location: new_admin_department_path,
+                        alert: department.errors.full_messages.join(", ")
+        end
+      end
+
+      def show
+        render inertia: "Escalated/Admin/Departments/Show", props: {
+          department: department_json(@department),
+          agents: @department.agents.map { |a|
+            { id: a.id, name: a.respond_to?(:name) ? a.name : a.email, email: a.email }
+          },
+          stats: {
+            total_tickets: @department.tickets.count,
+            open_tickets: @department.open_ticket_count,
+            agent_count: @department.agent_count
+          }
+        }
+      end
+
+      def edit
+        render inertia: "Escalated/Admin/Departments/Form", props: {
+          department: department_json(@department),
+          sla_policies: Escalated::SlaPolicy.active.ordered.map { |p| { id: p.id, name: p.name } },
+          agents: agent_list,
+          current_agent_ids: @department.agents.pluck(:id)
+        }
+      end
+
+      def update
+        if @department.update(department_params)
+          sync_agents(@department, params[:agent_ids]) if params.key?(:agent_ids)
+          redirect_to admin_department_path(@department), notice: "Department updated."
+        else
+          redirect_back fallback_location: edit_admin_department_path(@department),
+                        alert: @department.errors.full_messages.join(", ")
+        end
+      end
+
+      def destroy
+        @department.destroy!
+        redirect_to admin_departments_path, notice: "Department deleted."
+      end
+
+      private
+
+      def set_department
+        @department = Escalated::Department.find(params[:id])
+      end
+
+      def department_params
+        params.require(:department).permit(:name, :description, :email, :is_active, :default_sla_policy_id)
+      end
+
+      def sync_agents(department, agent_ids)
+        return unless agent_ids.present?
+
+        agents = Escalated.configuration.user_model.where(id: agent_ids)
+        department.agents = agents
+      end
+
+      def department_json(department)
+        {
+          id: department.id,
+          name: department.name,
+          slug: department.slug,
+          description: department.description,
+          email: department.email,
+          is_active: department.is_active,
+          default_sla_policy: department.default_sla_policy ? {
+            id: department.default_sla_policy.id,
+            name: department.default_sla_policy.name
+          } : nil,
+          agent_count: department.agent_count,
+          open_ticket_count: department.open_ticket_count,
+          created_at: department.created_at&.iso8601
+        }
+      end
+
+      def agent_list
+        if Escalated.configuration.user_model.respond_to?(:escalated_agents)
+          Escalated.configuration.user_model.escalated_agents.map { |a|
+            { id: a.id, name: a.respond_to?(:name) ? a.name : a.email, email: a.email }
+          }
+        else
+          []
+        end
+      end
+
+      def admin_department_path(department)
+        escalated.admin_department_path(department)
+      end
+
+      def new_admin_department_path
+        escalated.new_admin_department_path
+      end
+
+      def edit_admin_department_path(department)
+        escalated.edit_admin_department_path(department)
+      end
+
+      def admin_departments_path
+        escalated.admin_departments_path
+      end
+    end
+  end
+end