@fatagnus/convex-feedback 0.2.7 → 0.2.8

package/README.md

@@ -1,6 +1,6 @@
 # @fatagnus/convex-feedback
 
-Bug reports and feedback collection component for Convex applications with AI analysis and email notifications.
+Bug reports and feedback collection component for Convex applications with AI analysis, email notifications, and a REST API.
 
 ## Features
 
@@ -12,6 +12,9 @@ Bug reports and feedback collection component for Convex applications with AI an
 - 👥 **Support Teams** - Route notifications to the right teams based on type/severity
 - 📸 **Screenshots** - Capture or upload screenshots with reports
 - 🔄 **Real-time** - Leverages Convex for real-time updates
+- 🎫 **Ticket Numbers** - Human-readable ticket IDs (BUG-2025-0001, FB-2025-0001)
+- 🔑 **API Keys** - Secure API key management for external integrations
+- 🌐 **REST API** - HTTP endpoints for external tools (Codebuff, CLI tools, etc.)
 
 ## Installation
 
@@ -57,7 +60,25 @@ app.use(feedback);
 export default app;
 ```
 
-### 2. Configure Environment Variables
+### 2. Register HTTP Routes (Optional)
+
+To enable the REST API for external integrations:
+
+```typescript
+// convex/http.ts
+import { httpRouter } from "convex/server";
+import { registerFeedbackRoutes } from "@fatagnus/convex-feedback";
+
+const http = httpRouter();
+
+// Register feedback API routes with optional prefix
+registerFeedbackRoutes(http, { pathPrefix: "/feedback" });
+
+// Your other routes...
+export default http;
+```
+
+### 3. Configure Environment Variables
 
 Set these environment variables in your Convex dashboard:
 
@@ -67,7 +88,7 @@ Set these environment variables in your Convex dashboard:
 | `RESEND_API_KEY` | No | Resend API key for email notifications |
 | `RESEND_FROM_EMAIL` | No | From email address (default: `bugs@resend.dev`) |
 
-### 3. Add React Components
+### 4. Add React Components
 
 Wrap your app with the `BugReportProvider` and add the `BugReportButton`:
 
@@ -103,7 +124,293 @@ function App() {
 }
 ```
 
-## API Reference
+---
+
+## HTTP REST API
+
+The REST API allows external tools (like Codebuff, CLI tools, CI/CD pipelines) to interact with bug reports and feedback.
+
+### Authentication
+
+All endpoints require an API key in the `Authorization` header:
+
+```
+Authorization: Bearer fb_your_api_key_here
+```
+
+### Base URL
+
+Your Convex HTTP endpoint + the path prefix you configured:
+
+```
+https://your-deployment.convex.site/feedback/api/...
+```
+
+### Ticket Number Format
+
+All tickets have human-readable IDs:
+
+| Type | Format | Example |
+|------|--------|----------|
+| Bug Report | `BUG-YYYY-NNNN` | `BUG-2025-0001` |
+| Feedback | `FB-YYYY-NNNN` | `FB-2025-0042` |
+
+---
+
+### API Key Management
+
+API keys are managed via Convex mutations. The full key is only shown once at creation time.
+
+#### Create a Key
+
+```typescript
+const result = await ctx.runMutation(api.feedback.apiKeys.create, {
+  name: "My Integration",
+  expiresAt: Date.now() + 90 * 24 * 60 * 60 * 1000, // 90 days (optional)
+});
+
+console.log(result.key);       // fb_a1b2c3d4e5f6g7h8... (save this!)
+console.log(result.keyPrefix); // fb_a1b2c3d4
+```
+
+#### List Keys
+
+```typescript
+const keys = await ctx.runQuery(api.feedback.apiKeys.list, {});
+// Returns array of { _id, keyPrefix, name, expiresAt, isRevoked, isExpired, createdAt }
+```
+
+#### Revoke a Key
+
+```typescript
+await ctx.runMutation(api.feedback.apiKeys.revoke, {
+  keyPrefix: "fb_a1b2c3d4",
+});
+```
+
+#### Rotate a Key
+
+```typescript
+const newKey = await ctx.runMutation(api.feedback.apiKeys.rotate, {
+  keyPrefix: "fb_a1b2c3d4",
+  name: "Rotated Key", // optional
+  expiresAt: Date.now() + 90 * 24 * 60 * 60 * 1000, // optional
+});
+```
+
+---
+
+### Endpoints
+
+#### GET `/api/items`
+
+List bug reports and/or feedback items with optional filters.
+
+**Query Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `itemType` | `bug` \| `feedback` \| `all` | `all` | Filter by item type |
+| `status` | string | - | Filter by status |
+| `severity` | `low` \| `medium` \| `high` \| `critical` | - | Filter bugs by severity |
+| `priority` | `nice_to_have` \| `important` \| `critical` | - | Filter feedback by priority |
+| `type` | `feature_request` \| `change_request` \| `general` | - | Filter feedback by type |
+| `limit` | number | `50` | Max items to return |
+| `includeArchived` | `true` \| `false` | `false` | Include archived items |
+
+**Bug Status Values:** `open`, `in-progress`, `resolved`, `closed`
+
+**Feedback Status Values:** `open`, `under_review`, `planned`, `in_progress`, `completed`, `declined`
+
+**Example:**
+
+```bash
+# List all open bugs
+curl -H "Authorization: Bearer fb_your_key" \
+  "https://your-site.convex.site/feedback/api/items?itemType=bug&status=open"
+```
+
+**Response:**
+
+```json
+{
+  "bugs": [
+    {
+      "_id": "abc123",
+      "ticketNumber": "BUG-2025-0001",
+      "title": "Login button not working",
+      "severity": "high",
+      "status": "open",
+      ...
+    }
+  ],
+  "feedback": [...]
+}
+```
+
+---
+
+#### GET `/api/items/{ticketNumber}`
+
+Fetch a single bug report or feedback item by ticket number.
+
+**Example:**
+
+```bash
+curl -H "Authorization: Bearer fb_your_key" \
+  "https://your-site.convex.site/feedback/api/items/BUG-2025-0001"
+```
+
+**Response:**
+
+```json
+{
+  "type": "bug",
+  "_id": "abc123",
+  "ticketNumber": "BUG-2025-0001",
+  "title": "Login button not working",
+  "description": "When I click the login button, nothing happens",
+  "severity": "high",
+  "status": "open",
+  "aiSummary": "The login form submit handler is not properly bound",
+  "aiRootCauseAnalysis": "React event handler not attached correctly",
+  "aiSuggestedFix": "Check that the onClick handler is properly bound",
+  ...
+}
+```
+
+---
+
+#### GET `/api/prompt/{ticketNumber}`
+
+Fetch an AI-generated prompt for fixing/implementing a ticket. Designed for AI coding assistants like Codebuff.
+
+**Query Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `template` | `fix` \| `implement` \| `analyze` \| `codebuff` | `fix` (bugs) / `implement` (feedback) | Prompt template |
+
+**Templates:**
+
+| Template | Use Case |
+|----------|----------|
+| `fix` | Bug fix instructions |
+| `implement` | Feature implementation instructions |
+| `analyze` | Deep analysis prompt |
+| `codebuff` | Codebuff-optimized structured format |
+
+**Example:**
+
+```bash
+# Get a Codebuff-optimized prompt
+curl -H "Authorization: Bearer fb_your_key" \
+  "https://your-site.convex.site/feedback/api/prompt/BUG-2025-0001?template=codebuff"
+```
+
+**Response:**
+
+```json
+{
+  "ticketNumber": "BUG-2025-0001",
+  "type": "bug",
+  "template": "codebuff",
+  "prompt": "# Bug Fix Request: BUG-2025-0001\n\n## Title\nLogin button not working\n\n..."
+}
+```
+
+---
+
+#### PATCH `/api/items/{ticketNumber}/status`
+
+Update the status of a bug report or feedback item.
+
+**Request Body:**
+
+```json
+{ "status": "resolved" }
+```
+
+**Example:**
+
+```bash
+curl -X PATCH \
+  -H "Authorization: Bearer fb_your_key" \
+  -H "Content-Type: application/json" \
+  -d '{"status": "resolved"}' \
+  "https://your-site.convex.site/feedback/api/items/BUG-2025-0001/status"
+```
+
+**Response:**
+
+```json
+{ "success": true, "ticketNumber": "BUG-2025-0001" }
+```
+
+---
+
+#### PATCH `/api/items/{ticketNumber}/archive`
+
+Archive or unarchive a bug report or feedback item.
+
+**Request Body:**
+
+```json
+{ "archived": true }
+```
+
+**Example:**
+
+```bash
+curl -X PATCH \
+  -H "Authorization: Bearer fb_your_key" \
+  -H "Content-Type: application/json" \
+  -d '{"archived": true}' \
+  "https://your-site.convex.site/feedback/api/items/BUG-2025-0001/archive"
+```
+
+**Response:**
+
+```json
+{ "success": true, "ticketNumber": "BUG-2025-0001", "isArchived": true }
+```
+
+---
+
+### Error Responses
+
+| Status | Response |
+|--------|----------|
+| 400 | `{ "error": "Bad request", "message": "..." }` |
+| 401 | `{ "error": "Unauthorized", "message": "Invalid or missing API key" }` |
+| 404 | `{ "error": "Not found", "message": "Bug report BUG-2025-0001 not found" }` |
+
+---
+
+### Integration Examples
+
+#### Codebuff Integration
+
+```bash
+curl -s -H "Authorization: Bearer fb_your_key" \
+  "https://your-site.convex.site/feedback/api/prompt/BUG-2025-0001?template=codebuff" \
+  | jq -r '.prompt' \
+  | codebuff
+```
+
+#### GitHub Actions
+
+```yaml
+- name: Get open bugs count
+  run: |
+    curl -s -H "Authorization: Bearer ${{ secrets.FEEDBACK_API_KEY }}" \
+      "${{ secrets.CONVEX_SITE_URL }}/feedback/api/items?itemType=bug&status=open" \
+      | jq '.bugs | length'
+```
+
+---
+
+## Convex API Reference
 
 ### Bug Reports
 
@@ -251,6 +558,8 @@ await ctx.runMutation(api.feedback.supportTeams.update, {
 });
 ```
 
+---
+
 ## React Components
 
 ### BugReportProvider
@@ -407,6 +716,8 @@ function MyComponent() {
 }
 ```
 
+---
+
 ## AI Interview Mode
 
 The AI Interview Mode provides a conversational experience to help users articulate their bug reports and feedback more effectively. Instead of filling out a form, users chat with an AI that asks clarifying questions and generates a well-structured report.
@@ -548,6 +859,8 @@ The AI can ask for input in three formats:
 - Users can always toggle between "AI Interview" and "Quick Form" modes
 - Screenshots and browser diagnostics are still captured automatically in interview mode
 
+---
+
 ## AI Analysis
 
 When `OPENROUTER_API_KEY` is configured, the component automatically analyzes submissions:
@@ -569,6 +882,8 @@ When `OPENROUTER_API_KEY` is configured, the component automatically analyzes su
 - **Estimated Effort** - Low/Medium/High effort estimate
 - **Suggested Priority** - AI-recommended priority level
 
+---
+
 ## Email Notifications
 
 When `RESEND_API_KEY` is configured, the component sends email notifications:
@@ -584,6 +899,8 @@ When `RESEND_API_KEY` is configured, the component sends email notifications:
 - Routed based on feedback type or bug severity
 - Rich HTML template with all diagnostics
 
+---
+
 ## Schema
 
 The component creates these tables:
@@ -593,6 +910,31 @@ The component creates these tables:
 - `supportTeams` - Team configuration for notification routing
 - `feedbackInputRequests` - Pending user input requests during AI interviews
 - `interviewSessions` - Interview state and generated reports
+- `ticketCounters` - Sequential counters for ticket numbers
+- `apiKeys` - API keys for REST API authentication
+
+---
+
+## TypeScript Types
+
+```typescript
+import type {
+  BugReport,
+  Feedback,
+  BugSeverity,
+  BugStatus,
+  FeedbackType,
+  FeedbackPriority,
+  FeedbackStatus,
+  ApiKey,
+  ApiKeyCreated,
+  PromptTemplate,
+  RegisterFeedbackRoutesOptions,
+  InterviewContext,
+} from '@fatagnus/convex-feedback';
+```
+
+---
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fatagnus/convex-feedback",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Bug reports and feedback collection component for Convex applications with AI analysis and email notifications",
   "license": "Apache-2.0",
   "repository": {
@@ -38,7 +38,8 @@
     },
     "./convex.config": "./src/convex/convex.config.ts",
     "./convex/*": "./src/convex/*",
-    "./convex/agents/*": "./src/convex/agents/*"
+    "./convex/agents/*": "./src/convex/agents/*",
+    "./convex/http": "./src/convex/http.ts"
   },
   "files": [
     "dist",
@@ -49,8 +50,12 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
+    "typecheck": "tsc --noEmit --project tsconfig.json",
+    "typecheck:convex": "tsc --noEmit --project src/convex/tsconfig.json",
+    "postgenerate": "node -e \"const fs=require('fs');const f='src/convex/_generated/api.ts';if(fs.existsSync(f)){let c=fs.readFileSync(f,'utf8');if(!c.includes('@ts-nocheck')){c=c.replace('/* eslint-disable */','/* eslint-disable */\\n// @ts-nocheck - Circular reference errors in generated Convex component types are expected');fs.writeFileSync(f,c)}}\"",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "peerDependencies": {
     "@ai-sdk/openai-compatible": ">=0.1.0",
@@ -101,6 +106,8 @@
   "devDependencies": {
     "@types/node": "^20.0.0",
     "@types/react": "^18.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0",
+    "convex-test": "^0.0.36"
   }
 }

package/src/convex/_generated/api.ts

@@ -1,4 +1,5 @@
 /* eslint-disable */
+// @ts-nocheck - Circular reference errors in generated Convex component types are expected
 /**
  * Generated `api` utility.
  *

package/src/convex/agents/feedbackInterviewAgent.ts

@@ -591,14 +591,12 @@ export const startBugInterview = action({
     });
 
     // Start the interview
+    // Note: Tools look up session by threadId, so we don't need to pass sessionId via customCtx
     let result;
     try {
       result = await dynamicAgent.generateText(
         ctx,
-        { 
-          threadId,
-          customCtx: { sessionId },
-        },
+        { threadId },
         { prompt: "Start the bug report interview. Greet the user briefly and ask what bug or issue they encountered." }
       );
     } catch (error) {
@@ -722,14 +720,12 @@ export const startFeedbackInterview = action({
     });
 
     // Start the interview
+    // Note: Tools look up session by threadId, so we don't need to pass sessionId via customCtx
     let result;
     try {
       result = await dynamicAgent.generateText(
         ctx,
-        { 
-          threadId,
-          customCtx: { sessionId },
-        },
+        { threadId },
         { prompt: "Start the feedback interview. Greet the user briefly and ask about their idea or suggestion." }
       );
     } catch (error) {
@@ -871,14 +867,12 @@ export const continueInterview = action({
     });
 
     // Continue the agent
+    // Note: Tools look up session by threadId, so we don't need to pass sessionId via customCtx
     let result;
     try {
       result = await dynamicAgent.generateText(
         ctx,
-        { 
-          threadId: args.threadId,
-          customCtx: { sessionId: args.sessionId },
-        },
+        { threadId: args.threadId },
         {
           prompt: `The user responded: ${args.response}
 

package/src/convex/apiKeys.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Unit tests for API Key utilities
+ * 
+ * Note: Testing Convex component packages with convex-test requires special setup.
+ * These tests verify the key format and structure expectations.
+ * Full integration tests should be run in a real Convex deployment.
+ */
+import { describe, it, expect } from "vitest";
+
+describe("API Key Format", () => {
+  describe("Key Structure", () => {
+    it("key format should be fb_ followed by 32 hex chars", () => {
+      // Example of expected format
+      const validKeyPattern = /^fb_[a-f0-9]{32}$/;
+      const exampleKey = "fb_0123456789abcdef0123456789abcdef";
+      
+      expect(exampleKey).toMatch(validKeyPattern);
+      expect(exampleKey.length).toBe(35); // "fb_" (3) + 32 hex chars
+    });
+
+    it("key prefix should be fb_ followed by 8 hex chars", () => {
+      const validPrefixPattern = /^fb_[a-f0-9]{8}$/;
+      const examplePrefix = "fb_01234567";
+      
+      expect(examplePrefix).toMatch(validPrefixPattern);
+      expect(examplePrefix.length).toBe(11); // "fb_" (3) + 8 hex chars
+    });
+
+    it("key prefix should be the first 11 chars of the full key", () => {
+      const fullKey = "fb_0123456789abcdef0123456789abcdef";
+      const expectedPrefix = fullKey.slice(0, 11);
+      
+      expect(expectedPrefix).toBe("fb_01234567");
+    });
+  });
+
+  describe("Key Hashing", () => {
+    it("SHA-256 hash should produce 64 hex chars", async () => {
+      const key = "fb_0123456789abcdef0123456789abcdef";
+      
+      const encoder = new TextEncoder();
+      const data = encoder.encode(key);
+      const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+      const hashArray = Array.from(new Uint8Array(hashBuffer));
+      const hashHex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+      
+      expect(hashHex.length).toBe(64);
+      expect(hashHex).toMatch(/^[a-f0-9]{64}$/);
+    });
+
+    it("same key should always produce same hash", async () => {
+      const key = "fb_testkey123456789abcdef12345678";
+      
+      const hash1 = await hashKey(key);
+      const hash2 = await hashKey(key);
+      
+      expect(hash1).toBe(hash2);
+    });
+
+    it("different keys should produce different hashes", async () => {
+      const key1 = "fb_testkey123456789abcdef12345678";
+      const key2 = "fb_testkey123456789abcdef12345679";
+      
+      const hash1 = await hashKey(key1);
+      const hash2 = await hashKey(key2);
+      
+      expect(hash1).not.toBe(hash2);
+    });
+  });
+});
+
+// Helper function matching the implementation in apiKeys.ts
+async function hashKey(key: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(key);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+}