@fatagnus/convex-feedback 0.1.0

package/src/convex/agents/feedbackAgent.ts

@@ -0,0 +1,264 @@
+/**
+ * Feedback AI Agent
+ *
+ * Automatically analyzes feedback submissions and generates:
+ * - Summary of the feedback
+ * - Impact analysis (affected areas, users, systems)
+ * - Suggested action items
+ * - Estimated effort (low/medium/high)
+ * - Priority recommendations
+ *
+ * Triggers email notifications to the reporter and assigned team.
+ */
+
+import { v } from "convex/values";
+import { Agent, createThread } from "@convex-dev/agent";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { components, internal } from "../_generated/api";
+import { internalAction, internalQuery } from "../_generated/server";
+import type { FeedbackPriority, Effort } from "../schema";
+
+// Create OpenRouter provider
+const openrouter = createOpenAICompatible({
+  name: "openrouter",
+  baseURL: "https://openrouter.ai/api/v1",
+  headers: {
+    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
+  },
+});
+
+// Agent name constant
+const AGENT_NAME = "Feedback Analyst";
+
+// ============================================================================
+// Agent Definition
+// ============================================================================
+
+/**
+ * Feedback Analysis Agent
+ *
+ * Analyzes feedback submissions and generates comprehensive reports.
+ */
+export const feedbackAgent = new Agent(components.agent, {
+  name: AGENT_NAME,
+  languageModel: openrouter.languageModel("anthropic/claude-sonnet-4"),
+
+  instructions: `You are the Feedback Analyst, an AI assistant that analyzes user feedback submissions.
+
+When given feedback, you will:
+1. **Summarize** the feedback in 2-3 clear sentences
+2. **Analyze Impact** - identify what areas, users, or systems are affected
+3. **Suggest Action Items** - provide 3-5 concrete next steps to address the feedback
+4. **Estimate Effort** - rate as "low" (< 1 week), "medium" (1-4 weeks), or "high" (> 4 weeks)
+5. **Recommend Priority** - suggest "nice_to_have", "important", or "critical" based on the feedback content
+
+## Response Format
+Always respond in the following JSON format:
+\`\`\`json
+{
+  "summary": "A 2-3 sentence summary of the feedback",
+  "impactAnalysis": "Detailed analysis of what's affected and potential consequences",
+  "actionItems": ["Action item 1", "Action item 2", "Action item 3"],
+  "estimatedEffort": "low" | "medium" | "high",
+  "suggestedPriority": "nice_to_have" | "important" | "critical",
+  "reasoning": "Brief explanation for your priority and effort estimates"
+}
+\`\`\`
+
+## Guidelines
+- Be objective and constructive in your analysis
+- Consider both technical and business impact
+- Action items should be specific and actionable
+- Effort estimation should account for development, testing, and deployment
+- Priority should reflect urgency and user impact`,
+
+  tools: {},
+  maxSteps: 3,
+});
+
+// ============================================================================
+// Internal Queries
+// ============================================================================
+
+/**
+ * Get feedback by ID for analysis
+ */
+export const getFeedbackForAnalysis = internalQuery({
+  args: {
+    feedbackId: v.id("feedback"),
+  },
+  returns: v.union(
+    v.object({
+      _id: v.id("feedback"),
+      type: v.string(),
+      title: v.string(),
+      description: v.string(),
+      priority: v.string(),
+      reporterName: v.string(),
+      reporterEmail: v.string(),
+      url: v.string(),
+      browserInfo: v.string(),
+    }),
+    v.null()
+  ),
+  handler: async (ctx, args) => {
+    const feedback = await ctx.db.get(args.feedbackId);
+    if (!feedback) {
+      return null;
+    }
+    return {
+      _id: feedback._id,
+      type: feedback.type,
+      title: feedback.title,
+      description: feedback.description,
+      priority: feedback.priority,
+      reporterName: feedback.reporterName,
+      reporterEmail: feedback.reporterEmail,
+      url: feedback.url,
+      browserInfo: feedback.browserInfo,
+    };
+  },
+});
+
+// ============================================================================
+// Main Processing Action
+// ============================================================================
+
+/**
+ * Analyze feedback using AI and send notifications.
+ * This is the main entry point triggered after feedback creation.
+ */
+export const processFeedback = internalAction({
+  args: {
+    feedbackId: v.id("feedback"),
+  },
+  returns: v.object({
+    success: v.boolean(),
+    error: v.optional(v.string()),
+  }),
+  handler: async (ctx, args): Promise<{ success: boolean; error?: string }> => {
+    // Check if OpenRouter API key is configured
+    if (!process.env.OPENROUTER_API_KEY) {
+      console.log("OPENROUTER_API_KEY not configured, skipping AI analysis");
+      // Still try to send notifications without AI analysis
+      try {
+        await ctx.runAction(internal.emails.feedbackEmails.sendFeedbackNotifications, {
+          feedbackId: args.feedbackId,
+          analysis: null,
+        });
+      } catch {
+        console.log("Email notifications not configured");
+      }
+      return { success: true };
+    }
+
+    // Get the feedback
+    const feedback = await ctx.runQuery(internal.agents.feedbackAgent.getFeedbackForAnalysis, {
+      feedbackId: args.feedbackId,
+    });
+
+    if (!feedback) {
+      return { success: false, error: "Feedback not found" };
+    }
+
+    // Create a thread for this analysis
+    const threadId = await createThread(ctx, components.agent, {
+      title: `Feedback Analysis: ${feedback.title}`,
+    });
+
+    // Build the prompt for analysis
+    const analysisPrompt = `Please analyze the following feedback submission:
+
+**Type:** ${feedback.type.replace("_", " ")}
+**Title:** ${feedback.title}
+**Description:** ${feedback.description}
+**Reporter Priority:** ${feedback.priority.replace("_", " ")}
+**Submitted From:** ${feedback.url}
+
+Provide your analysis in the JSON format specified.`;
+
+    // Generate analysis using the agent
+    let result: { text: string };
+    try {
+      result = await feedbackAgent.generateText(
+        ctx,
+        { threadId },
+        { prompt: analysisPrompt }
+      );
+    } catch (error) {
+      console.error("AI analysis failed:", error);
+      return { success: false, error: `AI analysis failed: ${error instanceof Error ? error.message : String(error)}` };
+    }
+
+    // Parse the AI response
+    let analysis: {
+      summary: string;
+      impactAnalysis: string;
+      actionItems: string[];
+      estimatedEffort: Effort;
+      suggestedPriority: FeedbackPriority;
+    };
+
+    try {
+      // Extract JSON from the response (handle markdown code blocks)
+      const jsonMatch = result.text.match(/```json\s*([\s\S]*?)\s*```/);
+      const jsonStr = jsonMatch ? jsonMatch[1] : result.text;
+      const parsed = JSON.parse(jsonStr);
+      
+      analysis = {
+        summary: parsed.summary || "Unable to generate summary",
+        impactAnalysis: parsed.impactAnalysis || "Unable to generate impact analysis",
+        actionItems: Array.isArray(parsed.actionItems) ? parsed.actionItems : [],
+        estimatedEffort: ["low", "medium", "high"].includes(parsed.estimatedEffort) 
+          ? parsed.estimatedEffort 
+          : "medium",
+        suggestedPriority: ["nice_to_have", "important", "critical"].includes(parsed.suggestedPriority)
+          ? parsed.suggestedPriority
+          : feedback.priority as FeedbackPriority,
+      };
+    } catch {
+      // If parsing fails, create a basic analysis from the text
+      analysis = {
+        summary: result.text.substring(0, 500),
+        impactAnalysis: "AI analysis parsing failed. Please review manually.",
+        actionItems: ["Review feedback manually", "Contact reporter for clarification"],
+        estimatedEffort: "medium",
+        suggestedPriority: feedback.priority as FeedbackPriority,
+      };
+    }
+
+    // Update feedback with analysis
+    await ctx.runMutation(internal.feedback.updateWithAnalysis, {
+      feedbackId: args.feedbackId,
+      aiSummary: analysis.summary,
+      aiImpactAnalysis: analysis.impactAnalysis,
+      aiActionItems: analysis.actionItems,
+      aiEstimatedEffort: analysis.estimatedEffort,
+      aiSuggestedPriority: analysis.suggestedPriority,
+      aiThreadId: threadId,
+    });
+
+    // Send email notifications
+    try {
+      await ctx.runAction(internal.emails.feedbackEmails.sendFeedbackNotifications, {
+        feedbackId: args.feedbackId,
+        analysis: {
+          summary: analysis.summary,
+          impactAnalysis: analysis.impactAnalysis,
+          actionItems: analysis.actionItems,
+          estimatedEffort: analysis.estimatedEffort,
+          suggestedPriority: analysis.suggestedPriority,
+        },
+      });
+
+      // Mark notifications as sent
+      await ctx.runMutation(internal.feedback.markNotificationsSent, {
+        feedbackId: args.feedbackId,
+      });
+    } catch {
+      console.log("Email notifications not configured or failed");
+    }
+
+    return { success: true };
+  },
+});

package/src/convex/bugReports.ts

@@ -0,0 +1,350 @@
+import { v } from "convex/values";
+import { mutation, query, internalMutation } from "./_generated/server";
+import { internal } from "./_generated/api";
+import {
+  bugSeverityValidator,
+  bugStatusValidator,
+  reporterTypeValidator,
+  effortValidator,
+} from "./schema";
+
+// Return validator for bug reports
+const bugReportReturnValidator = v.object({
+  _id: v.id("bugReports"),
+  _creationTime: v.number(),
+  title: v.string(),
+  description: v.string(),
+  severity: bugSeverityValidator,
+  status: bugStatusValidator,
+  isArchived: v.optional(v.boolean()),
+  reporterType: reporterTypeValidator,
+  reporterId: v.string(),
+  reporterEmail: v.string(),
+  reporterName: v.string(),
+  url: v.string(),
+  route: v.optional(v.string()),
+  browserInfo: v.string(),
+  consoleErrors: v.optional(v.string()),
+  screenshotStorageId: v.optional(v.id("_storage")),
+  viewportWidth: v.number(),
+  viewportHeight: v.number(),
+  networkState: v.string(),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+  // AI Analysis fields
+  aiSummary: v.optional(v.string()),
+  aiRootCauseAnalysis: v.optional(v.string()),
+  aiReproductionSteps: v.optional(v.array(v.string())),
+  aiSuggestedFix: v.optional(v.string()),
+  aiEstimatedEffort: v.optional(effortValidator),
+  aiSuggestedSeverity: v.optional(bugSeverityValidator),
+  aiAnalyzedAt: v.optional(v.number()),
+  aiThreadId: v.optional(v.string()),
+  notificationsSentAt: v.optional(v.number()),
+});
+
+/**
+ * Create a new bug report.
+ * This mutation is intentionally public (no auth required) because:
+ * 1. We want to capture bugs even when auth might be broken
+ * 2. The reporter info is passed explicitly from the client
+ */
+export const create = mutation({
+  args: {
+    title: v.string(),
+    description: v.string(),
+    severity: bugSeverityValidator,
+    reporterType: reporterTypeValidator,
+    reporterId: v.string(),
+    reporterEmail: v.string(),
+    reporterName: v.string(),
+    url: v.string(),
+    route: v.optional(v.string()),
+    browserInfo: v.string(),
+    consoleErrors: v.optional(v.string()),
+    screenshotStorageId: v.optional(v.id("_storage")),
+    viewportWidth: v.number(),
+    viewportHeight: v.number(),
+    networkState: v.string(),
+  },
+  returns: v.id("bugReports"),
+  handler: async (ctx, args) => {
+    const now = Date.now();
+
+    const reportId = await ctx.db.insert("bugReports", {
+      title: args.title,
+      description: args.description,
+      severity: args.severity,
+      status: "open",
+      reporterType: args.reporterType,
+      reporterId: args.reporterId,
+      reporterEmail: args.reporterEmail,
+      reporterName: args.reporterName,
+      url: args.url,
+      route: args.route,
+      browserInfo: args.browserInfo,
+      consoleErrors: args.consoleErrors,
+      screenshotStorageId: args.screenshotStorageId,
+      viewportWidth: args.viewportWidth,
+      viewportHeight: args.viewportHeight,
+      networkState: args.networkState,
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    // Schedule AI analysis and email notifications (runs immediately)
+    // This uses a try-catch to gracefully handle if agents aren't configured
+    try {
+      await ctx.scheduler.runAfter(0, internal.agents.bugReportAgent.processBugReport, {
+        bugReportId: reportId,
+      });
+    } catch {
+      // AI agent not available, continue without analysis
+      console.log("AI agent not configured, skipping analysis");
+    }
+
+    return reportId;
+  },
+});
+
+/**
+ * List bug reports with optional filters.
+ * By default, archived items are excluded unless includeArchived is true.
+ */
+export const list = query({
+  args: {
+    status: v.optional(bugStatusValidator),
+    severity: v.optional(bugSeverityValidator),
+    includeArchived: v.optional(v.boolean()),
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(bugReportReturnValidator),
+  handler: async (ctx, args) => {
+    const limit = args.limit ?? 50;
+    const includeArchived = args.includeArchived ?? false;
+
+    let reports;
+    if (args.status) {
+      const status = args.status;
+      reports = await ctx.db
+        .query("bugReports")
+        .withIndex("by_status", (q) => q.eq("status", status))
+        .order("desc")
+        .take(limit * 2);
+    } else if (args.severity) {
+      const severity = args.severity;
+      reports = await ctx.db
+        .query("bugReports")
+        .withIndex("by_severity", (q) => q.eq("severity", severity))
+        .order("desc")
+        .take(limit * 2);
+    } else {
+      reports = await ctx.db
+        .query("bugReports")
+        .withIndex("by_created")
+        .order("desc")
+        .take(limit * 2);
+    }
+
+    // Filter out archived items unless includeArchived is true
+    if (!includeArchived) {
+      reports = reports.filter((r) => !r.isArchived);
+    }
+
+    return reports.slice(0, limit);
+  },
+});
+
+/**
+ * Get a single bug report by ID.
+ */
+export const get = query({
+  args: {
+    reportId: v.id("bugReports"),
+  },
+  returns: v.union(bugReportReturnValidator, v.null()),
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.reportId);
+  },
+});
+
+/**
+ * Update bug report status.
+ */
+export const updateStatus = mutation({
+  args: {
+    reportId: v.id("bugReports"),
+    status: bugStatusValidator,
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const report = await ctx.db.get(args.reportId);
+    if (!report) {
+      throw new Error("Bug report not found");
+    }
+
+    await ctx.db.patch(args.reportId, {
+      status: args.status,
+      updatedAt: Date.now(),
+    });
+
+    return null;
+  },
+});
+
+/**
+ * Generate upload URL for screenshot.
+ */
+export const generateUploadUrl = mutation({
+  args: {},
+  returns: v.string(),
+  handler: async (ctx) => {
+    return await ctx.storage.generateUploadUrl();
+  },
+});
+
+/**
+ * Get screenshot URL from storage ID.
+ */
+export const getScreenshotUrl = query({
+  args: {
+    storageId: v.id("_storage"),
+  },
+  returns: v.union(v.string(), v.null()),
+  handler: async (ctx, args) => {
+    return await ctx.storage.getUrl(args.storageId);
+  },
+});
+
+/**
+ * Archive a bug report.
+ */
+export const archive = mutation({
+  args: {
+    reportId: v.id("bugReports"),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const report = await ctx.db.get(args.reportId);
+    if (!report) {
+      throw new Error("Bug report not found");
+    }
+
+    await ctx.db.patch(args.reportId, {
+      isArchived: true,
+      updatedAt: Date.now(),
+    });
+
+    return null;
+  },
+});
+
+/**
+ * Unarchive a bug report.
+ */
+export const unarchive = mutation({
+  args: {
+    reportId: v.id("bugReports"),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const report = await ctx.db.get(args.reportId);
+    if (!report) {
+      throw new Error("Bug report not found");
+    }
+
+    await ctx.db.patch(args.reportId, {
+      isArchived: false,
+      updatedAt: Date.now(),
+    });
+
+    return null;
+  },
+});
+
+/**
+ * Get AI analysis for a specific bug report.
+ */
+export const getAiAnalysis = query({
+  args: {
+    reportId: v.id("bugReports"),
+  },
+  returns: v.union(
+    v.object({
+      aiSummary: v.union(v.string(), v.null()),
+      aiRootCauseAnalysis: v.union(v.string(), v.null()),
+      aiReproductionSteps: v.union(v.array(v.string()), v.null()),
+      aiSuggestedFix: v.union(v.string(), v.null()),
+      aiEstimatedEffort: v.union(effortValidator, v.null()),
+      aiSuggestedSeverity: v.union(bugSeverityValidator, v.null()),
+      aiAnalyzedAt: v.union(v.number(), v.null()),
+      notificationsSentAt: v.union(v.number(), v.null()),
+    }),
+    v.null()
+  ),
+  handler: async (ctx, args) => {
+    const report = await ctx.db.get(args.reportId);
+    if (!report) {
+      return null;
+    }
+
+    return {
+      aiSummary: report.aiSummary ?? null,
+      aiRootCauseAnalysis: report.aiRootCauseAnalysis ?? null,
+      aiReproductionSteps: report.aiReproductionSteps ?? null,
+      aiSuggestedFix: report.aiSuggestedFix ?? null,
+      aiEstimatedEffort: report.aiEstimatedEffort ?? null,
+      aiSuggestedSeverity: report.aiSuggestedSeverity ?? null,
+      aiAnalyzedAt: report.aiAnalyzedAt ?? null,
+      notificationsSentAt: report.notificationsSentAt ?? null,
+    };
+  },
+});
+
+/**
+ * Internal mutation to update bug report with AI analysis results
+ */
+export const updateWithAnalysis = internalMutation({
+  args: {
+    bugReportId: v.id("bugReports"),
+    aiSummary: v.string(),
+    aiRootCauseAnalysis: v.string(),
+    aiReproductionSteps: v.array(v.string()),
+    aiSuggestedFix: v.string(),
+    aiEstimatedEffort: effortValidator,
+    aiSuggestedSeverity: bugSeverityValidator,
+    aiThreadId: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await ctx.db.patch(args.bugReportId, {
+      aiSummary: args.aiSummary,
+      aiRootCauseAnalysis: args.aiRootCauseAnalysis,
+      aiReproductionSteps: args.aiReproductionSteps,
+      aiSuggestedFix: args.aiSuggestedFix,
+      aiEstimatedEffort: args.aiEstimatedEffort,
+      aiSuggestedSeverity: args.aiSuggestedSeverity,
+      aiThreadId: args.aiThreadId,
+      aiAnalyzedAt: Date.now(),
+      updatedAt: Date.now(),
+    });
+    return null;
+  },
+});
+
+/**
+ * Internal mutation to mark notifications as sent
+ */
+export const markNotificationsSent = internalMutation({
+  args: {
+    bugReportId: v.id("bugReports"),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await ctx.db.patch(args.bugReportId, {
+      notificationsSentAt: Date.now(),
+      updatedAt: Date.now(),
+    });
+    return null;
+  },
+});

package/src/convex/convex.config.ts

@@ -0,0 +1,7 @@
+import { defineComponent } from "convex/server";
+import agent from "@convex-dev/agent/convex.config";
+
+const feedback = defineComponent("feedback");
+feedback.use(agent);
+
+export default feedback;