jat-feedback 1.7.0 → 2.0.0

package/README.md

@@ -32,6 +32,269 @@ The package includes the widget bundle, Supabase migration, and edge function
 | `user-role` | No | `''` | User's role (e.g., `admin`, `user`) |
 | `org-id` | No | `''` | Organization/tenant ID |
 | `org-name` | No | `''` | Organization name |
+| `agent-proxy` | No | `''` | URL path for the LLM proxy endpoint (e.g., `'/api/feedback/agent'`). Enables the Agent tab. |
+| `agent-model` | No | `'claude-sonnet-4-6'` | LLM model identifier passed to the proxy endpoint |
+| `agent-context` | No | `''` | Static app context injected into Agent system prompt (describe your app, key pages, nav) |
+
+## Agent Tab: LLM Proxy Endpoint
+
+The Agent tab lets users control the host page with natural language commands (powered by [page-agent](https://github.com/alibaba/page-agent)). To use it, set `agent-proxy` to a URL on your server that forwards LLM API calls. **API keys stay server-side — the widget never sees them.**
+
+### How It Works
+
+```
+Widget (browser)                    Your Server                     LLM Provider
+─────────────────                   ────────────                    ────────────
+User types command
+  → page-agent builds prompt
+  → POST /api/feedback/agent ────→ Receives request
+                                    Adds API key from env
+                                    POST api.anthropic.com ──────→ Processes request
+                                    ← Response ◄──────────────────── Returns completion
+  ← JSON response ◄──────────────
+  → Agent executes action on page
+```
+
+### Proxy Endpoint Spec
+
+Your server implements a single endpoint:
+
+- **Method:** `POST`
+- **Path:** Whatever you set in `agent-proxy` (e.g., `/api/feedback/agent`)
+- **Request body:** OpenAI-compatible chat completion request
+
+```json
+{
+  "model": "claude-sonnet-4-6",
+  "messages": [
+    { "role": "system", "content": "..." },
+    { "role": "user", "content": "Click the login button" }
+  ],
+  "tools": [...]
+}
+```
+
+- **Response:** OpenAI-compatible chat completion response
+- **Auth:** Your endpoint adds the API key server-side — the widget sends no auth headers
+
+### SvelteKit Example
+
+Create `src/routes/api/feedback/agent/[...path]/+server.ts`:
+
+```typescript
+import { json, error } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+import { ANTHROPIC_API_KEY } from '$env/static/private';
+
+export const POST: RequestHandler = async ({ request, params }) => {
+  const path = params.path || 'chat/completions';
+  const body = await request.json();
+
+  const response = await fetch(`https://api.anthropic.com/v1/${path}`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': ANTHROPIC_API_KEY,
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => '');
+    throw error(response.status, `LLM API error: ${detail.slice(0, 200)}`);
+  }
+
+  const data = await response.json();
+  return json(data);
+};
+```
+
+**Environment variable** (`.env`):
+```
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+### Widget Usage
+
+```html
+<jat-feedback
+  endpoint="http://localhost:5173"
+  project="my-app"
+  agent-proxy="/api/feedback/agent"
+  agent-model="claude-sonnet-4-6"
+></jat-feedback>
+```
+
+The Agent tab appears automatically when `agent-proxy` is set. Without it, only the feedback form and history tabs are shown.
+
+### Error Handling
+
+The widget handles proxy errors gracefully:
+
+| HTTP Status | User Message |
+|-------------|-------------|
+| 401 / 403 | "Check that the server has a valid API key configured" |
+| 429 | "Too many requests — wait a moment and try again" |
+| 500+ | Server error with detail from response body |
+| Timeout (60s) | "The server may be overloaded — try again" |
+| Network error | "Check that your server is running" |
+
+## Agent Notes: CRUD Endpoints
+
+Agent notes store user-written markdown context that gets injected into the page-agent's system prompt. Notes have two scopes: **site-wide** (`route` is `null`) and **per-route** (keyed by URL pathname). Requires the `1.8.0_add_agent_notes.sql` migration.
+
+### Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/feedback/notes?project=X` | List all notes for a project |
+| `GET` | `/api/feedback/notes?project=X&route=/path` | Get note for a specific route |
+| `PUT` | `/api/feedback/notes` | Create or update a note (upsert by project+route) |
+| `DELETE` | `/api/feedback/notes/:id` | Delete a note |
+
+### SvelteKit Example
+
+Create `src/routes/api/feedback/notes/+server.ts`:
+
+```typescript
+import { json } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+
+const CORS_HEADERS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, PUT, DELETE, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type',
+  'Access-Control-Max-Age': '86400'
+};
+
+export const OPTIONS: RequestHandler = async () => {
+  return new Response(null, { status: 204, headers: CORS_HEADERS });
+};
+
+// GET /api/feedback/notes?project=X[&route=/path]
+export const GET: RequestHandler = async ({ url, locals }) => {
+  const project = url.searchParams.get('project');
+  if (!project) {
+    return json({ error: 'project parameter is required' }, { status: 400, headers: CORS_HEADERS });
+  }
+
+  const supabase = locals.supabaseServiceRole;
+  let query = supabase.from('agent_notes').select('*').eq('project', project);
+
+  const route = url.searchParams.get('route');
+  if (route !== null) {
+    query = query.eq('route', route);
+  }
+
+  const { data, error } = await query.order('updated_at', { ascending: false });
+
+  if (error) {
+    return json({ error: error.message }, { status: 500, headers: CORS_HEADERS });
+  }
+
+  return json({ notes: data }, { headers: CORS_HEADERS });
+};
+
+// PUT /api/feedback/notes — upsert by project + route
+export const PUT: RequestHandler = async ({ request, locals }) => {
+  const body = await request.json();
+
+  if (!body.project || typeof body.project !== 'string') {
+    return json({ error: 'project is required' }, { status: 400, headers: CORS_HEADERS });
+  }
+
+  const supabase = locals.supabaseServiceRole;
+  const route = body.route ?? null;
+
+  // Check if note already exists for this project+route
+  let query = supabase.from('agent_notes').select('id').eq('project', body.project);
+  if (route === null) {
+    query = query.is('route', null);
+  } else {
+    query = query.eq('route', route);
+  }
+  const { data: existing } = await query.maybeSingle();
+
+  let data, error;
+  if (existing) {
+    // Update existing note
+    ({ data, error } = await supabase
+      .from('agent_notes')
+      .update({ title: body.title ?? '', content: body.content ?? '' })
+      .eq('id', existing.id)
+      .select()
+      .single());
+  } else {
+    // Insert new note
+    ({ data, error } = await supabase
+      .from('agent_notes')
+      .insert({ project: body.project, route, title: body.title ?? '', content: body.content ?? '' })
+      .select()
+      .single());
+  }
+
+  if (error) {
+    return json({ error: error.message }, { status: 500, headers: CORS_HEADERS });
+  }
+
+  return json({ ok: true, note: data }, { status: existing ? 200 : 201, headers: CORS_HEADERS });
+};
+```
+
+Create `src/routes/api/feedback/notes/[id]/+server.ts`:
+
+```typescript
+import { json } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+
+const CORS_HEADERS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'DELETE, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type',
+  'Access-Control-Max-Age': '86400'
+};
+
+export const OPTIONS: RequestHandler = async () => {
+  return new Response(null, { status: 204, headers: CORS_HEADERS });
+};
+
+// DELETE /api/feedback/notes/:id
+export const DELETE: RequestHandler = async ({ params, locals }) => {
+  const supabase = locals.supabaseServiceRole;
+
+  const { error } = await supabase
+    .from('agent_notes')
+    .delete()
+    .eq('id', params.id);
+
+  if (error) {
+    return json({ error: error.message }, { status: 500, headers: CORS_HEADERS });
+  }
+
+  return json({ ok: true }, { headers: CORS_HEADERS });
+};
+```
+
+### Upsert Behavior
+
+The `PUT` endpoint checks for an existing note matching `project` + `route`, then inserts or updates accordingly. The database has a unique index on `(project, COALESCE(route, ''))` as a safety net.
+
+- If no note exists for the given `project` + `route` → creates a new note (returns `201`)
+- If a note already exists for that combination → updates `title`, `content`, and `updated_at` (returns `200`)
+- Site-wide notes use `route: null` (only one per project)
+- Per-route notes use the URL pathname (e.g., `route: "/invoices"`)
+
+### CORS
+
+All endpoints include permissive CORS headers (`Access-Control-Allow-Origin: *`) so the widget can call them cross-origin. For production, restrict the origin to your widget's domain:
+
+```typescript
+const CORS_HEADERS = {
+  'Access-Control-Allow-Origin': 'https://your-app.com',
+  // ...
+};
+```
 
 ## What the Widget Captures