jat-feedback 1.1.0 → 1.2.0

package/README.md

@@ -11,25 +11,11 @@ User clicks "Report Bug" → Widget captures context → POST /api/feedback/repo
 
 ## Install
 
-### Option 1: CDN (recommended)
-
-```html
-<script src="https://unpkg.com/jat-feedback@^1/dist/jat-feedback.js"></script>
-<jat-feedback project="my-app"></jat-feedback>
-<script>
-  document.querySelector('jat-feedback').setAttribute('endpoint', location.origin);
-</script>
-```
-
-### Option 2: npm
-
 ```bash
 npm install jat-feedback
 ```
 
-```js
-import 'jat-feedback';
-```
+The package includes the widget bundle, Supabase migration, and edge function — all three are needed for the full pipeline.
 
 ## Widget Attributes
 
@@ -82,9 +68,32 @@ Full setup for any SvelteKit app with Supabase. Creates the feedback pipeline fr
 
 ### Step 1: Add Widget to app.html
 
+The widget is a web component bundled at `dist/jat-feedback.js`. Use `vite-plugin-static-copy` to copy it into your build output, then load it from your own server.
+
+**vite.config.ts:**
+```typescript
+import { sveltekit } from '@sveltejs/vite-plugin-svelte';
+import { viteStaticCopy } from 'vite-plugin-static-copy';
+
+export default {
+  plugins: [
+    sveltekit(),
+    viteStaticCopy({
+      targets: [
+        {
+          src: 'node_modules/jat-feedback/dist/jat-feedback.js',
+          dest: '.'
+        }
+      ]
+    })
+  ]
+};
+```
+
+**src/app.html:**
 ```html
-<!-- src/app.html — before closing </body> tag -->
-<script src="https://unpkg.com/jat-feedback@^1/dist/jat-feedback.js"></script>
+<!-- before closing </body> tag -->
+<script src="/jat-feedback.js"></script>
 <jat-feedback project="YOUR_PROJECT"></jat-feedback>
 <script>
   (function() {
@@ -164,7 +173,6 @@ export const POST: RequestHandler = async ({ request, locals }) => {
     }
 
     const reporter = body.metadata?.reporter || {};
-    const org = body.metadata?.organization || {};
 
     const { data: row, error: insertError } = await supabase
       .from('feedback_reports')
@@ -179,8 +187,6 @@ export const POST: RequestHandler = async ({ request, locals }) => {
         reporter_email: reporter.email || null,
         reporter_name: reporter.name || null,
         reporter_role: reporter.role || null,
-        organization_id: org.id || null,
-        organization_name: org.name || null,
         console_logs: body.console_logs || null,
         selected_elements: body.selected_elements || null,
         screenshot_paths: screenshotPaths.length > 0 ? screenshotPaths : null,
@@ -208,104 +214,21 @@ export const POST: RequestHandler = async ({ request, locals }) => {
 };
 ```
 
-**Note:** If your app doesn't have organizations, remove the `organization_id` and `organization_name` fields from the insert and from the migration (Step 3).
-
-### Step 3: Supabase Migration
-
-Create a migration file (e.g., `supabase/migrations/YYYYMMDD000000_feedback_reports.sql`):
-
-```sql
--- Feedback reports table for jat-feedback widget
--- Widget POSTs to /api/feedback/report → this table
--- JAT ingest daemon polls for jat_status = 'new'
-
-CREATE TABLE IF NOT EXISTS feedback_reports (
-  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
-  title TEXT NOT NULL,
-  description TEXT DEFAULT '',
-  type TEXT DEFAULT 'bug' CHECK (type IN ('bug', 'enhancement', 'other')),
-  priority TEXT DEFAULT 'medium' CHECK (priority IN ('low', 'medium', 'high', 'critical')),
-  page_url TEXT,
-  user_agent TEXT,
-
-  -- Reporter identity
-  reporter_user_id UUID REFERENCES auth.users(id),
-  reporter_email TEXT,
-  reporter_name TEXT,
-  reporter_role TEXT,
-
-  -- Organization context (remove if not applicable)
-  organization_id UUID,
-  organization_name TEXT,
-
-  -- Structured data
-  console_logs JSONB,
-  selected_elements JSONB,
-  screenshot_paths TEXT[],
-  metadata JSONB,
-
-  -- JAT ingest tracking
-  jat_status TEXT DEFAULT 'new' CHECK (jat_status IN ('new', 'ingested', 'failed', 'rejected')),
-  jat_task_id TEXT,
-
-  -- User-facing status tracking
-  status TEXT DEFAULT 'submitted'
-    CHECK (status IN ('submitted', 'in_progress', 'completed', 'wontfix', 'closed')),
-  dev_notes TEXT,
-  user_response TEXT CHECK (user_response IN ('accepted', 'rejected')),
-  user_response_at TIMESTAMPTZ,
-  rejection_reason TEXT,
-
-  created_at TIMESTAMPTZ DEFAULT now()
-);
-
--- Indexes
-CREATE INDEX idx_feedback_reports_jat_status ON feedback_reports(jat_status) WHERE jat_status = 'new';
-CREATE INDEX idx_feedback_reports_jat_rejected ON feedback_reports(jat_status) WHERE jat_status = 'rejected';
-CREATE INDEX idx_feedback_reports_reporter ON feedback_reports(reporter_user_id, created_at DESC);
-
--- Storage bucket for screenshots
-INSERT INTO storage.buckets (id, name, public) VALUES ('feedback-screenshots', 'feedback-screenshots', false)
-ON CONFLICT (id) DO NOTHING;
-
--- RLS policies
-ALTER TABLE feedback_reports ENABLE ROW LEVEL SECURITY;
-
-CREATE POLICY "Authenticated users can insert feedback"
-  ON feedback_reports FOR INSERT TO authenticated
-  WITH CHECK (true);
-
-CREATE POLICY "Users can read own feedback reports"
-  ON feedback_reports FOR SELECT TO authenticated
-  USING (reporter_user_id = auth.uid());
-
-CREATE POLICY "Users can respond to own feedback"
-  ON feedback_reports FOR UPDATE TO authenticated
-  USING (reporter_user_id = auth.uid())
-  WITH CHECK (reporter_user_id = auth.uid());
-
-CREATE POLICY "Service role full access to feedback"
-  ON feedback_reports FOR ALL TO service_role
-  USING (true) WITH CHECK (true);
-
--- Storage policies
-CREATE POLICY "Authenticated users can upload feedback screenshots"
-  ON storage.objects FOR INSERT TO authenticated
-  WITH CHECK (bucket_id = 'feedback-screenshots');
-
-CREATE POLICY "Service role can read feedback screenshots"
-  ON storage.objects FOR SELECT TO service_role
-  USING (bucket_id = 'feedback-screenshots');
-```
+### Step 3: Run the Supabase Migration
 
-Push the migration:
+The `feedback_reports` table schema is included in this package. Copy it into your migrations folder and push:
 
 ```bash
+# Copy the migration (rename to match your timestamp convention)
+cp node_modules/jat-feedback/supabase/migrations/1.0.0_feedback_reports.sql \
+   supabase/migrations/$(date +%Y%m%d%H%M%S)_feedback_reports.sql
+
+# Push to Supabase
 supabase db push
-# or
-supabase migration up
 ```
 
+**When upgrading jat-feedback:** check `node_modules/jat-feedback/supabase/migrations/` for new versioned files (e.g. `1.1.0_*.sql`) and copy+apply any you haven't run yet.
+
 ### Step 4: Wire User Context
 
 In your authenticated layout, set widget attributes after login so reports include user identity.
@@ -323,8 +246,6 @@ onMount(() => {
       // Adjust based on where your app stores display name:
       if (user.user_metadata?.full_name) el.setAttribute('user-name', user.user_metadata.full_name);
       if (user.user_metadata?.role) el.setAttribute('user-role', user.user_metadata.role);
-      // If your app has organizations:
-      // if (user.organization_id) el.setAttribute('org-id', user.organization_id);
     }
   }
 });
@@ -372,12 +293,11 @@ Add this entry to the `sources` array.
     "labels": ["widget", "feedback"]
   },
   "table": "feedback_reports",
-  "statusColumn": "jat_status",
-  "statusNew": "new",
-  "statusDone": "ingested",
+  "statusColumn": "status",
+  "statusNew": "submitted",
   "taskIdColumn": "jat_task_id",
   "titleColumn": "title",
-  "descriptionTemplate": "**Reporter:** {reporter_name} ({reporter_email})\n**Page:** {page_url}\n**Browser:** {user_agent}\n\n{description}",
+  "descriptionTemplate": "**Reporter:** {reporter_name} ({reporter_email}) — {reporter_role}\n**Page:** {page_url}\n**Browser:** {user_agent}\n\n{description}",
   "authorColumn": "reporter_email",
   "timestampColumn": "created_at",
   "attachmentColumn": "screenshot_paths",
@@ -404,12 +324,11 @@ Add this entry to the `sources` array.
   "projectUrl": "https://YOUR_SUPABASE_PROJECT_ID.supabase.co",
   "secretName": "YOUR_PROJECT-supabase-service-role",
   "table": "feedback_reports",
-  "statusColumn": "jat_status",
-  "statusNew": "new",
-  "statusDone": "ingested",
+  "statusColumn": "status",
+  "statusNew": "submitted",
   "taskIdColumn": "jat_task_id",
   "titleColumn": "title",
-  "descriptionTemplate": "**Reporter:** {reporter_name} ({reporter_email})\n**Page:** {page_url}\n**Browser:** {user_agent}\n\n{description}",
+  "descriptionTemplate": "**Reporter:** {reporter_name} ({reporter_email}) — {reporter_role}\n**Page:** {page_url}\n**Browser:** {user_agent}\n\n{description}",
   "authorColumn": "reporter_email",
   "timestampColumn": "created_at",
   "attachmentColumn": "screenshot_paths",
@@ -437,16 +356,53 @@ Add this entry to the `sources` array.
     },
     "referenceTable": "feedback_reports",
     "referenceIdFrom": "item_id"
-  }
+  },
+  "actions": [
+    {
+      "id": "sync_status",
+      "label": "Sync Status",
+      "description": "Push current task status to Supabase",
+      "type": "callback",
+      "event": "status_changed",
+      "icon": "refresh"
+    },
+    {
+      "id": "open_record",
+      "label": "View in Supabase",
+      "description": "Open the original feedback report in Supabase dashboard",
+      "type": "link",
+      "urlTemplate": "{projectUrl}/project/default/editor/feedback_reports?filter=id%3Deq.{referenceId}",
+      "icon": "external-link"
+    }
+  ]
 }
 ```
 
 - **automation**: Auto-spawn an agent when a report is ingested
-- **callback**: Push JAT task status changes back to Supabase (requires a Supabase Edge Function to receive the webhook)
+- **callback**: Push JAT task status changes back to Supabase — requires deploying the `jat-webhook` edge function (see Step 6)
+- **actions**: Adds "Sync Status" and "View in Supabase" buttons in the JAT IDE task panel
 
 The ingest daemon picks up config changes automatically (no restart needed).
 
-### Step 6: Verify
+### Step 6: Deploy the JAT Webhook Edge Function (for callbacks)
+
+The `jat-webhook` Supabase Edge Function receives status-change callbacks from JAT and updates your `feedback_reports` rows. It's included in this package — copy it into your project and deploy it.
+
+```bash
+# Copy the function into your project
+mkdir -p supabase/functions/jat-webhook
+cp node_modules/jat-feedback/supabase/functions/jat-webhook/index.ts \
+   supabase/functions/jat-webhook/index.ts
+
+# Deploy to Supabase
+supabase functions deploy jat-webhook
+```
+
+The function uses `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` — both are injected automatically by Supabase, no extra configuration needed.
+
+**Skip this step** if you don't need bidirectional status sync (i.e., you only want JAT to ingest reports, not push status back to Supabase).
+
+### Step 7: Verify
 
 ```bash
 # Check the API endpoint is working
@@ -471,14 +427,14 @@ jat ingest status
 │  jat-feedback │────►│  Your App    │────►│   Supabase   │────►│  JAT Ingest  │
 │  (widget)     │     │  /api/report │     │  feedback_   │     │  Daemon      │
 │              │     │              │     │  reports     │     │              │
-└──────────────┘     └──────────────┘     └──────────────┘     └──────┬───────┘
-                                                                       │
-                                                                       ▼
-                                                               ┌──────────────┐
-                                                               │  JAT Task    │
-                                                               │  (auto-      │
-                                                               │   created)   │
-                                                               └──────────────┘
+└──────────────┘     └──────────────┘     └──────┬───────┘     └──────┬───────┘
+                                                 ▲                    │
+                                                 │                    ▼
+                                          ┌──────┴───────┐   ┌──────────────┐
+                                          │  jat-webhook  │◄──│  JAT Task    │
+                                          │  (edge fn)    │   │  status      │
+                                          │  status sync  │   │  changes     │
+                                          └──────────────┘   └──────────────┘
 ```
 
 ## Column Reference
@@ -487,11 +443,72 @@ The `feedback_reports` table columns used by the pipeline:
 
 | Column | Type | Purpose |
 |--------|------|---------|
-| `jat_status` | TEXT | Ingest state: `new` → `ingested` (or `failed`, `rejected`) |
+| `status` | TEXT | Lifecycle: `submitted` → `in_progress` → `completed` → `accepted` \| `rejected` |
 | `jat_task_id` | TEXT | JAT task ID written back after ingest (e.g., `myapp-abc`) |
-| `status` | TEXT | User-facing status synced from JAT task lifecycle |
+| `rejection_reason` | TEXT | User-provided reason when rejecting a completed report |
 | `dev_notes` | TEXT | Developer notes pushed back via callback |
-| `user_response` | TEXT | User accept/reject of completed fix |
+
+## Upgrading
+
+npm never auto-updates — you need to explicitly upgrade and then handle each type of change manually.
+
+```bash
+# 1. Update the package
+npm install jat-feedback@latest
+```
+
+Then handle whatever changed in the release notes:
+
+**Widget JS changes** (UI, behavior, new attributes):
+```bash
+# Nothing extra — the updated bundle is copied to your build output automatically
+# Just redeploy your app
+```
+
+**Schema changes** (new columns, indexes):
+```bash
+# Check for new migration files
+ls node_modules/jat-feedback/supabase/migrations/
+
+# Copy any new ones into your project and run them
+cp node_modules/jat-feedback/supabase/migrations/1.1.0_*.sql \
+   supabase/migrations/$(date +%Y%m%d%H%M%S)_feedback_1_1_0.sql
+
+supabase db push
+```
+
+**Edge function changes** (webhook behavior):
+```bash
+# Re-copy and redeploy
+cp node_modules/jat-feedback/supabase/functions/jat-webhook/index.ts \
+   supabase/functions/jat-webhook/index.ts
+
+supabase functions deploy jat-webhook
+```
+
+## Versioning
+
+This package follows semver. The `^` range in consuming projects (`"jat-feedback": "^1.1.0"`) means:
+
+- **Patch and minor** (1.1.x, 1.2.0) — auto-accepted by `npm install`
+- **Major** (2.0.0) — requires manual version bump in `package.json`
+
+### What triggers a major version
+
+| Change | Version |
+|--------|---------|
+| New nullable column (additive) | patch/minor |
+| New widget attribute (optional) | minor |
+| Removing or renaming a column | **major** |
+| Changing a column's type | **major** |
+| Renaming `status` values (e.g. `submitted` → `new`) | **major** |
+| Required integrations.json config field added/renamed | **major** |
+
+### Rule for additive schema changes
+
+Any column added in a `1.x` release **must** be nullable with no required default. This ensures consuming projects don't break even if they haven't run the migration yet — the insert just omits the column and it lands as `NULL`.
+
+If a new column is required (non-nullable, no default), that's a breaking change and belongs in a major version.
 
 ## License