feat: support ticket system with private threads and channel mode

migrations/014_tickets.cjs

@@ -0,0 +1,47 @@
+/**
+ * Migration 014 — Tickets
+ * Creates the tickets table for the support ticket system.
+ *
+ * @see https://github.com/VolvoxLLC/volvox-bot/issues/134
+ */
+
+'use strict';
+
+/**
+ * @param {import('pg').Pool} pool
+ */
+async function up(pool) {
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS tickets (
+      id SERIAL PRIMARY KEY,
+      guild_id TEXT NOT NULL,
+      user_id TEXT NOT NULL,
+      topic TEXT,
+      status TEXT NOT NULL DEFAULT 'open' CHECK (status IN ('open', 'closed')),
+      thread_id TEXT NOT NULL,
+      channel_id TEXT,
+      closed_by TEXT,
+      close_reason TEXT,
+      created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      closed_at TIMESTAMPTZ,
+      transcript JSONB
+    );
+  `);
+
+  await pool.query(`
+    CREATE INDEX IF NOT EXISTS idx_tickets_guild_status
+      ON tickets(guild_id, status);
+  `);
+
+  await pool.query(`
+    CREATE INDEX IF NOT EXISTS idx_tickets_user
+      ON tickets(guild_id, user_id);
+  `);
+
+  await pool.query(`
+    CREATE INDEX IF NOT EXISTS idx_tickets_thread_status
+      ON tickets(thread_id, status);
+  `);
+}
+
+module.exports = { up };

src/api/index.js

@@ -13,6 +13,7 @@ import guildsRouter from './routes/guilds.js';
 import healthRouter from './routes/health.js';
 import membersRouter from './routes/members.js';
 import moderationRouter from './routes/moderation.js';
+import ticketsRouter from './routes/tickets.js';
 import webhooksRouter from './routes/webhooks.js';
 
 const router = Router();
@@ -37,6 +38,10 @@ router.use('/guilds', requireAuth(), membersRouter);
 // (mounted before guilds to handle /:id/conversations/* before the catch-all guild endpoint)
 router.use('/guilds/:id/conversations', requireAuth(), conversationsRouter);
 
+// Ticket routes — require API secret or OAuth2 JWT
+// (mounted before guilds to handle /:id/tickets/* before the catch-all guild endpoint)
+router.use('/guilds', requireAuth(), ticketsRouter);
+
 // Guild routes — require API secret or OAuth2 JWT
 router.use('/guilds', requireAuth(), guildsRouter);
 

src/api/routes/tickets.js

@@ -0,0 +1,180 @@
+/**
+ * Ticket API Routes
+ * Exposes ticket data for the web dashboard.
+ *
+ * @see https://github.com/VolvoxLLC/volvox-bot/issues/134
+ */
+
+import { Router } from 'express';
+import { error as logError } from '../../logger.js';
+import { rateLimit } from '../middleware/rateLimit.js';
+import { requireGuildAdmin, validateGuild } from './guilds.js';
+
+const router = Router();
+
+/** Rate limiter for ticket API endpoints — 30 req/min per IP. */
+const ticketRateLimit = rateLimit({ windowMs: 60 * 1000, max: 30 });
+
+/**
+ * Helper to get the database pool from app.locals.
+ *
+ * @param {import('express').Request} req
+ * @returns {import('pg').Pool | null}
+ */
+function getDbPool(req) {
+  return req.app.locals.dbPool || null;
+}
+
+// ─── GET /:id/tickets/stats ───────────────────────────────────────────────────
+
+/**
+ * GET /:id/tickets/stats — Ticket statistics for a guild.
+ * Returns open count, avg resolution time, and tickets this week.
+ */
+router.get(
+  '/:id/tickets/stats',
+  ticketRateLimit,
+  requireGuildAdmin,
+  validateGuild,
+  async (req, res) => {
+    const { id: guildId } = req.params;
+    const pool = getDbPool(req);
+    if (!pool) return res.status(503).json({ error: 'Database not available' });
+
+    try {
+      const [openResult, avgResult, weekResult] = await Promise.all([
+        pool.query(
+          'SELECT COUNT(*)::int AS count FROM tickets WHERE guild_id = $1 AND status = $2',
+          [guildId, 'open'],
+        ),
+        pool.query(
+          `SELECT COALESCE(
+          EXTRACT(EPOCH FROM AVG(closed_at - created_at))::int, 0
+        ) AS avg_seconds
+        FROM tickets
+        WHERE guild_id = $1 AND status = 'closed' AND closed_at IS NOT NULL`,
+          [guildId],
+        ),
+        pool.query(
+          `SELECT COUNT(*)::int AS count
+         FROM tickets
+         WHERE guild_id = $1 AND created_at >= NOW() - INTERVAL '7 days'`,
+          [guildId],
+        ),
+      ]);
+
+      res.json({
+        openCount: openResult.rows[0].count,
+        avgResolutionSeconds: avgResult.rows[0].avg_seconds,
+        ticketsThisWeek: weekResult.rows[0].count,
+      });
+    } catch (err) {
+      logError('Failed to fetch ticket stats', { guildId, error: err.message });
+      res.status(500).json({ error: 'Failed to fetch ticket stats' });
+    }
+  },
+);
+
+// ─── GET /:id/tickets/:ticketId ───────────────────────────────────────────────
+
+/**
+ * GET /:id/tickets/:ticketId — Ticket detail with transcript.
+ */
+router.get(
+  '/:id/tickets/:ticketId',
+  ticketRateLimit,
+  requireGuildAdmin,
+  validateGuild,
+  async (req, res) => {
+    const { id: guildId, ticketId } = req.params;
+    const pool = getDbPool(req);
+    if (!pool) return res.status(503).json({ error: 'Database not available' });
+
+    const parsedId = Number.parseInt(ticketId, 10);
+    if (Number.isNaN(parsedId)) {
+      return res.status(400).json({ error: 'Invalid ticket ID' });
+    }
+
+    try {
+      const { rows } = await pool.query('SELECT * FROM tickets WHERE guild_id = $1 AND id = $2', [
+        guildId,
+        parsedId,
+      ]);
+
+      if (rows.length === 0) {
+        return res.status(404).json({ error: 'Ticket not found' });
+      }
+
+      res.json(rows[0]);
+    } catch (err) {
+      logError('Failed to fetch ticket detail', { guildId, ticketId, error: err.message });
+      res.status(500).json({ error: 'Failed to fetch ticket' });
+    }
+  },
+);
+
+// ─── GET /:id/tickets ─────────────────────────────────────────────────────────
+
+/**
+ * GET /:id/tickets — List tickets with pagination and filters.
+ *
+ * Query params:
+ *   status  — Filter by status (open, closed)
+ *   user    — Filter by user ID
+ *   page    — Page number (default 1)
+ *   limit   — Items per page (default 25, max 100)
+ */
+router.get('/:id/tickets', ticketRateLimit, requireGuildAdmin, validateGuild, async (req, res) => {
+  const { id: guildId } = req.params;
+  const { status, user } = req.query;
+  const page = Math.max(1, Number.parseInt(req.query.page, 10) || 1);
+  const limit = Math.min(100, Math.max(1, Number.parseInt(req.query.limit, 10) || 25));
+  const offset = (page - 1) * limit;
+  const pool = getDbPool(req);
+  if (!pool) return res.status(503).json({ error: 'Database not available' });
+
+  try {
+    const conditions = ['guild_id = $1'];
+    const params = [guildId];
+    let paramIndex = 2;
+
+    if (status && (status === 'open' || status === 'closed')) {
+      conditions.push(`status = $${paramIndex}`);
+      params.push(status);
+      paramIndex++;
+    }
+
+    if (user) {
+      conditions.push(`user_id = $${paramIndex}`);
+      params.push(user);
+      paramIndex++;
+    }
+
+    const whereClause = conditions.join(' AND ');
+
+    const [countResult, ticketsResult] = await Promise.all([
+      pool.query(`SELECT COUNT(*)::int AS total FROM tickets WHERE ${whereClause}`, params),
+      pool.query(
+        `SELECT id, guild_id, user_id, topic, status, thread_id, channel_id,
+                closed_by, close_reason, created_at, closed_at
+         FROM tickets
+         WHERE ${whereClause}
+         ORDER BY created_at DESC
+         LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`,
+        [...params, limit, offset],
+      ),
+    ]);
+
+    res.json({
+      tickets: ticketsResult.rows,
+      total: countResult.rows[0].total,
+      page,
+      limit,
+    });
+  } catch (err) {
+    logError('Failed to fetch tickets', { guildId, error: err.message });
+    res.status(500).json({ error: 'Failed to fetch tickets' });
+  }
+});
+
+export default router;