@fatagnus/convex-feedback 0.2.7 → 0.2.9

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