@fatagnus/convex-feedback 0.2.7 → 0.2.8

package/src/convex/http.ts

@@ -0,0 +1,630 @@
+import { httpRouter, HttpRouter } from "convex/server";
+import { httpAction } from "./_generated/server";
+import { internal } from "./_generated/api";
+import { generateBugPrompt, generateFeedbackPrompt, PromptTemplate } from "./prompts";
+import type { RegisterFeedbackRoutesOptions } from "../types";
+
+export type { RegisterFeedbackRoutesOptions };
+
+/**
+ * Validate API key from Authorization header
+ */
+async function validateApiKey(
+  ctx: { runQuery: (fn: unknown, args: unknown) => Promise<unknown>; runMutation?: (fn: unknown, args: unknown) => Promise<unknown> },
+  authHeader: string | null
+): Promise<boolean> {
+  if (!authHeader) {
+    return false;
+  }
+
+  // Expect: "Bearer fb_xxxxx"
+  const match = authHeader.match(/^Bearer\s+(.+)$/i);
+  if (!match) {
+    return false;
+  }
+
+  const key = match[1];
+  return (await ctx.runQuery(internal.apiKeys.validateKey, { key })) as boolean;
+}
+
+/**
+ * Parse template from query string
+ */
+function parseTemplate(url: URL): PromptTemplate {
+  const template = url.searchParams.get("template");
+  if (template === "fix" || template === "implement" || template === "analyze" || template === "codebuff") {
+    return template;
+  }
+  // Return undefined to let the caller decide the default
+  return "fix";
+}
+
+/**
+ * Register all feedback HTTP routes on the provided router.
+ * 
+ * This allows consumer apps to integrate the feedback API into their own HTTP router.
+ * 
+ * @example
+ * ```typescript
+ * // In your app's convex/http.ts:
+ * import { httpRouter } from "convex/server";
+ * import { registerFeedbackRoutes } from "@convex-dev/feedback/convex";
+ * 
+ * const http = httpRouter();
+ * 
+ * // Register feedback routes with optional prefix
+ * registerFeedbackRoutes(http, { pathPrefix: "/feedback" });
+ * 
+ * // Your other routes...
+ * http.route({ path: "/api/health", method: "GET", handler: ... });
+ * 
+ * export default http;
+ * ```
+ * 
+ * Registered routes:
+ * - GET  {prefix}/api/prompt/{ticketNumber} - Fetch AI prompt for a ticket
+ * - GET  {prefix}/api/items - List bug reports and feedback
+ * - GET  {prefix}/api/items/{ticketNumber} - Get a single item
+ * - PATCH {prefix}/api/items/{ticketNumber}/status - Update item status
+ * - PATCH {prefix}/api/items/{ticketNumber}/archive - Archive/unarchive item
+ * 
+ * @param router - The HttpRouter to register routes on
+ * @param options - Optional configuration
+ */
+export function registerFeedbackRoutes(
+  router: HttpRouter,
+  options: RegisterFeedbackRoutesOptions = {}
+): void {
+  const prefix = options.pathPrefix ?? "";
+
+  // GET /api/prompt/{ticketNumber}
+  router.route({
+    path: `${prefix}/api/prompt/{ticketNumber}`,
+    method: "GET",
+    handler: httpAction(async (ctx, request) => {
+    // Validate API key
+    const authHeader = request.headers.get("Authorization");
+    const isValid = await validateApiKey(ctx, authHeader);
+
+    if (!isValid) {
+      return new Response(
+        JSON.stringify({ error: "Unauthorized", message: "Invalid or missing API key" }),
+        {
+          status: 401,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    // Extract ticket number from URL
+    const url = new URL(request.url);
+    const pathParts = url.pathname.split("/");
+    const ticketNumber = pathParts[pathParts.length - 1]?.toUpperCase();
+
+    if (!ticketNumber) {
+      return new Response(
+        JSON.stringify({ error: "Bad request", message: "Missing ticket number" }),
+        {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    const template = parseTemplate(url);
+    const isBug = ticketNumber.startsWith("BUG-");
+    const isFeedback = ticketNumber.startsWith("FB-");
+
+    if (!isBug && !isFeedback) {
+      return new Response(
+        JSON.stringify({ error: "Bad request", message: "Invalid ticket number format" }),
+        {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    if (isBug) {
+      const bug = await ctx.runQuery(internal.prompts.getBugByTicketNumber, { ticketNumber });
+
+      if (!bug) {
+        return new Response(
+          JSON.stringify({ error: "Not found", message: `Bug report ${ticketNumber} not found` }),
+          {
+            status: 404,
+            headers: { "Content-Type": "application/json" },
+          }
+        );
+      }
+
+      const prompt = generateBugPrompt(
+        {
+          ticketNumber: bug.ticketNumber,
+          title: bug.title,
+          description: bug.description,
+          severity: bug.severity,
+          url: bug.url,
+          route: bug.route,
+          browserInfo: bug.browserInfo,
+          consoleErrors: bug.consoleErrors,
+          viewportWidth: bug.viewportWidth,
+          viewportHeight: bug.viewportHeight,
+          aiSummary: bug.aiSummary,
+          aiRootCauseAnalysis: bug.aiRootCauseAnalysis,
+          aiReproductionSteps: bug.aiReproductionSteps,
+          aiSuggestedFix: bug.aiSuggestedFix,
+          aiEstimatedEffort: bug.aiEstimatedEffort,
+          createdAt: bug.createdAt,
+        },
+        template
+      );
+
+      return new Response(
+        JSON.stringify({
+          ticketNumber: bug.ticketNumber,
+          type: "bug",
+          template,
+          prompt,
+        }),
+        {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    // Feedback
+    const feedback = await ctx.runQuery(internal.prompts.getFeedbackByTicketNumber, { ticketNumber });
+
+    if (!feedback) {
+      return new Response(
+        JSON.stringify({ error: "Not found", message: `Feedback ${ticketNumber} not found` }),
+        {
+          status: 404,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    // For feedback, default to "implement" instead of "fix"
+    const feedbackTemplate = template === "fix" && !url.searchParams.has("template") ? "implement" : template;
+
+    const prompt = generateFeedbackPrompt(
+      {
+        ticketNumber: feedback.ticketNumber,
+        type: feedback.type,
+        title: feedback.title,
+        description: feedback.description,
+        priority: feedback.priority,
+        url: feedback.url,
+        route: feedback.route,
+        aiSummary: feedback.aiSummary,
+        aiImpactAnalysis: feedback.aiImpactAnalysis,
+        aiActionItems: feedback.aiActionItems,
+        aiEstimatedEffort: feedback.aiEstimatedEffort,
+        createdAt: feedback.createdAt,
+      },
+      feedbackTemplate
+    );
+
+      return new Response(
+        JSON.stringify({
+          ticketNumber: feedback.ticketNumber,
+          type: "feedback",
+          template: feedbackTemplate,
+          prompt,
+        }),
+        {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }),
+  });
+
+  // GET /api/items/{ticketNumber}
+  /**
+   * GET /api/items/{ticketNumber}
+ * 
+ * Fetch a single bug report or feedback item by ticket number.
+ * 
+ * Path params:
+ * - ticketNumber: e.g., "BUG-2025-0001" or "FB-2025-0001"
+ * 
+ * Headers:
+ * - Authorization: Bearer <api-key>
+ * 
+ * Returns:
+ * - 200: Full item data
+ * - 400: { error: "Bad request" }
+ * - 401: { error: "Unauthorized" }
+ * - 404: { error: "Not found" }
+ */
+  router.route({
+    path: `${prefix}/api/items/{ticketNumber}`,
+    method: "GET",
+    handler: httpAction(async (ctx, request) => {
+    const authHeader = request.headers.get("Authorization");
+    const isValid = await validateApiKey(ctx, authHeader);
+
+    if (!isValid) {
+      return new Response(
+        JSON.stringify({ error: "Unauthorized", message: "Invalid or missing API key" }),
+        { status: 401, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    // Extract ticket number from URL
+    const url = new URL(request.url);
+    const pathParts = url.pathname.split("/");
+    const ticketNumber = pathParts[pathParts.length - 1]?.toUpperCase();
+
+    if (!ticketNumber) {
+      return new Response(
+        JSON.stringify({ error: "Bad request", message: "Missing ticket number" }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    const isBug = ticketNumber.startsWith("BUG-");
+    const isFeedback = ticketNumber.startsWith("FB-");
+
+    if (!isBug && !isFeedback) {
+      return new Response(
+        JSON.stringify({ error: "Bad request", message: "Invalid ticket number format. Expected BUG-YYYY-NNNN or FB-YYYY-NNNN" }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    if (isBug) {
+      const bug = await ctx.runQuery(internal.prompts.getBugByTicketNumber, { ticketNumber });
+
+      if (!bug) {
+        return new Response(
+          JSON.stringify({ error: "Not found", message: `Bug report ${ticketNumber} not found` }),
+          { status: 404, headers: { "Content-Type": "application/json" } }
+        );
+      }
+
+      return new Response(
+        JSON.stringify({ type: "bug", ...bug }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    // Feedback
+    const feedback = await ctx.runQuery(internal.prompts.getFeedbackByTicketNumber, { ticketNumber });
+
+    if (!feedback) {
+      return new Response(
+        JSON.stringify({ error: "Not found", message: `Feedback ${ticketNumber} not found` }),
+        { status: 404, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    return new Response(
+      JSON.stringify({ type: "feedback", ...feedback }),
+      { status: 200, headers: { "Content-Type": "application/json" } }
+    );
+    }),
+  });
+
+  // GET /api/items
+  /**
+   * GET /api/items
+ * 
+ * List bug reports and/or feedback items with optional filters.
+ * 
+ * Query params:
+ * - itemType: "bug" | "feedback" | "all" (default: "all")
+ * - status: filter by status (bug: open|in-progress|resolved|closed, feedback: open|under_review|planned|in_progress|completed|declined)
+ * - severity: filter bugs by severity (low|medium|high|critical)
+ * - priority: filter feedback by priority (nice_to_have|important|critical)
+ * - type: filter feedback by type (feature_request|change_request|general)
+ * - limit: max items to return (default: 50)
+ * - includeArchived: include archived items (default: false)
+ * 
+ * Headers:
+ * - Authorization: Bearer <api-key>
+ * 
+ * Returns:
+ * - 200: { bugs: [...], feedback: [...] }
+ * - 401: { error: "Unauthorized" }
+ */
+  router.route({
+    path: `${prefix}/api/items`,
+    method: "GET",
+    handler: httpAction(async (ctx, request) => {
+    const authHeader = request.headers.get("Authorization");
+    const isValid = await validateApiKey(ctx, authHeader);
+
+    if (!isValid) {
+      return new Response(
+        JSON.stringify({ error: "Unauthorized", message: "Invalid or missing API key" }),
+        { status: 401, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    const url = new URL(request.url);
+    const itemType = url.searchParams.get("itemType") ?? "all";
+    const status = url.searchParams.get("status");
+    const severity = url.searchParams.get("severity");
+    const priority = url.searchParams.get("priority");
+    const feedbackType = url.searchParams.get("type");
+    const limitParam = url.searchParams.get("limit");
+    const limit = limitParam ? parseInt(limitParam, 10) : 50;
+    const includeArchived = url.searchParams.get("includeArchived") === "true";
+
+    const result: { bugs?: unknown[]; feedback?: unknown[] } = {};
+
+    // Fetch bugs if requested
+    if (itemType === "bug" || itemType === "all") {
+      const bugArgs: Record<string, unknown> = { limit, includeArchived };
+      if (status && ["open", "in-progress", "resolved", "closed"].includes(status)) {
+        bugArgs.status = status;
+      }
+      if (severity && ["low", "medium", "high", "critical"].includes(severity)) {
+        bugArgs.severity = severity;
+      }
+      result.bugs = (await ctx.runQuery(internal.bugReports.listInternal, bugArgs)) as unknown[];
+    }
+
+    // Fetch feedback if requested
+    if (itemType === "feedback" || itemType === "all") {
+      const feedbackArgs: Record<string, unknown> = { limit, includeArchived };
+      if (status && ["open", "under_review", "planned", "in_progress", "completed", "declined"].includes(status)) {
+        feedbackArgs.status = status;
+      }
+      if (priority && ["nice_to_have", "important", "critical"].includes(priority)) {
+        feedbackArgs.priority = priority;
+      }
+      if (feedbackType && ["feature_request", "change_request", "general"].includes(feedbackType)) {
+        feedbackArgs.type = feedbackType;
+      }
+      result.feedback = (await ctx.runQuery(internal.feedback.listInternal, feedbackArgs)) as unknown[];
+    }
+
+    return new Response(JSON.stringify(result), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+    }),
+  });
+
+  // PATCH /api/items/{ticketNumber}/status
+  /**
+   * PATCH /api/items/{ticketNumber}/status
+ * 
+ * Update the status of a bug report or feedback item.
+ * 
+ * Path params:
+ * - ticketNumber: e.g., "BUG-2025-0001" or "FB-2025-0001"
+ * 
+ * Body (JSON):
+ * - status: new status value
+ *   - For bugs: "open" | "in-progress" | "resolved" | "closed"
+ *   - For feedback: "open" | "under_review" | "planned" | "in_progress" | "completed" | "declined"
+ * 
+ * Headers:
+ * - Authorization: Bearer <api-key>
+ * - Content-Type: application/json
+ * 
+ * Returns:
+ * - 200: { success: true, ticketNumber: "..." }
+ * - 400: { error: "Bad request" }
+ * - 401: { error: "Unauthorized" }
+ * - 404: { error: "Not found" }
+ */
+  router.route({
+    path: `${prefix}/api/items/{ticketNumber}/status`,
+    method: "PATCH",
+    handler: httpAction(async (ctx, request) => {
+    const authHeader = request.headers.get("Authorization");
+    const isValid = await validateApiKey(ctx, authHeader);
+
+    if (!isValid) {
+      return new Response(
+        JSON.stringify({ error: "Unauthorized", message: "Invalid or missing API key" }),
+        { status: 401, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    // Extract ticket number from URL
+    const url = new URL(request.url);
+    const pathParts = url.pathname.split("/");
+    // Path is /api/items/{ticketNumber}/status, so ticketNumber is second to last
+    const ticketNumber = pathParts[pathParts.length - 2]?.toUpperCase();
+
+    if (!ticketNumber) {
+      return new Response(
+        JSON.stringify({ error: "Bad request", message: "Missing ticket number" }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    const isBug = ticketNumber.startsWith("BUG-");
+    const isFeedback = ticketNumber.startsWith("FB-");
+
+    if (!isBug && !isFeedback) {
+      return new Response(
+        JSON.stringify({ error: "Bad request", message: "Invalid ticket number format. Expected BUG-YYYY-NNNN or FB-YYYY-NNNN" }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    // Parse request body
+    let body: { status?: string };
+    try {
+      body = await request.json();
+    } catch {
+      return new Response(
+        JSON.stringify({ error: "Bad request", message: "Invalid JSON body" }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    if (!body.status) {
+      return new Response(
+        JSON.stringify({ error: "Bad request", message: "Missing status in request body" }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    // Validate status based on type
+    const bugStatuses = ["open", "in-progress", "resolved", "closed"];
+    const feedbackStatuses = ["open", "under_review", "planned", "in_progress", "completed", "declined"];
+
+    if (isBug && !bugStatuses.includes(body.status)) {
+      return new Response(
+        JSON.stringify({ error: "Bad request", message: `Invalid bug status. Expected one of: ${bugStatuses.join(", ")}` }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    if (isFeedback && !feedbackStatuses.includes(body.status)) {
+      return new Response(
+        JSON.stringify({ error: "Bad request", message: `Invalid feedback status. Expected one of: ${feedbackStatuses.join(", ")}` }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    // Update the status
+    let result;
+    if (isBug) {
+      result = await ctx.runMutation(internal.bugReports.updateStatusByTicketNumber, {
+        ticketNumber,
+        status: body.status as "open" | "in-progress" | "resolved" | "closed",
+      });
+    } else {
+      result = await ctx.runMutation(internal.feedback.updateStatusByTicketNumber, {
+        ticketNumber,
+        status: body.status as "open" | "under_review" | "planned" | "in_progress" | "completed" | "declined",
+      });
+    }
+
+    if (!result) {
+      return new Response(
+        JSON.stringify({ error: "Not found", message: `Item ${ticketNumber} not found` }),
+        { status: 404, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    return new Response(JSON.stringify(result), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+    }),
+  });
+
+  // PATCH /api/items/{ticketNumber}/archive
+  /**
+   * PATCH /api/items/{ticketNumber}/archive
+ * 
+ * Archive or unarchive a bug report or feedback item.
+ * 
+ * Path params:
+ * - ticketNumber: e.g., "BUG-2025-0001" or "FB-2025-0001"
+ * 
+ * Body (JSON):
+ * - archived: boolean (true to archive, false to unarchive)
+ * 
+ * Headers:
+ * - Authorization: Bearer <api-key>
+ * - Content-Type: application/json
+ * 
+ * Returns:
+ * - 200: { success: true, ticketNumber: "...", isArchived: true/false }
+ * - 400: { error: "Bad request" }
+ * - 401: { error: "Unauthorized" }
+ * - 404: { error: "Not found" }
+ */
+  router.route({
+    path: `${prefix}/api/items/{ticketNumber}/archive`,
+    method: "PATCH",
+    handler: httpAction(async (ctx, request) => {
+    const authHeader = request.headers.get("Authorization");
+    const isValid = await validateApiKey(ctx, authHeader);
+
+    if (!isValid) {
+      return new Response(
+        JSON.stringify({ error: "Unauthorized", message: "Invalid or missing API key" }),
+        { status: 401, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    // Extract ticket number from URL
+    const url = new URL(request.url);
+    const pathParts = url.pathname.split("/");
+    // Path is /api/items/{ticketNumber}/archive, so ticketNumber is second to last
+    const ticketNumber = pathParts[pathParts.length - 2]?.toUpperCase();
+
+    if (!ticketNumber) {
+      return new Response(
+        JSON.stringify({ error: "Bad request", message: "Missing ticket number" }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    const isBug = ticketNumber.startsWith("BUG-");
+    const isFeedback = ticketNumber.startsWith("FB-");
+
+    if (!isBug && !isFeedback) {
+      return new Response(
+        JSON.stringify({ error: "Bad request", message: "Invalid ticket number format. Expected BUG-YYYY-NNNN or FB-YYYY-NNNN" }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    // Parse request body
+    let body: { archived?: boolean };
+    try {
+      body = await request.json();
+    } catch {
+      return new Response(
+        JSON.stringify({ error: "Bad request", message: "Invalid JSON body" }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    if (typeof body.archived !== "boolean") {
+      return new Response(
+        JSON.stringify({ error: "Bad request", message: "Missing or invalid 'archived' boolean in request body" }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    // Update the archive status
+    let result;
+    if (isBug) {
+      result = await ctx.runMutation(internal.bugReports.setArchivedByTicketNumber, {
+        ticketNumber,
+        isArchived: body.archived,
+      });
+    } else {
+      result = await ctx.runMutation(internal.feedback.setArchivedByTicketNumber, {
+        ticketNumber,
+        isArchived: body.archived,
+      });
+    }
+
+    if (!result) {
+      return new Response(
+        JSON.stringify({ error: "Not found", message: `Item ${ticketNumber} not found` }),
+        { status: 404, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    return new Response(JSON.stringify(result), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+    }),
+  });
+}
+
+// Create a standalone router for backwards compatibility / standalone usage
+const http = httpRouter();
+registerFeedbackRoutes(http);
+
+export default http;

package/src/convex/index.ts

@@ -10,6 +10,11 @@ export * as feedback from './feedback';
 export * as supportTeams from './supportTeams';
 export * as inputRequests from './inputRequests';
 export * as agents from './agents';
+export * as apiKeys from './apiKeys';
+export * as prompts from './prompts';
+
+// Export HTTP route registration helper
+export { registerFeedbackRoutes, type RegisterFeedbackRoutesOptions } from './http';
 
 // Re-export schema types and validators
 export {
@@ -20,6 +25,7 @@ export {
   feedbackStatusValidator,
   reporterTypeValidator,
   effortValidator,
+  counterTypeValidator,
   type BugSeverity,
   type BugStatus,
   type FeedbackType,
@@ -27,4 +33,9 @@ export {
   type FeedbackStatus,
   type ReporterType,
   type Effort,
+  type CounterType,
 } from './schema';
+
+// Re-export prompt template type
+export type { PromptTemplate } from './prompts';
+export { promptTemplateValidator } from './prompts';