jat-feedback 1.1.1 → 1.3.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() {
@@ -441,19 +450,66 @@ The `feedback_reports` table columns used by the pipeline:
 
 ## Upgrading
 
-When a new version adds schema changes, a new versioned migration file will appear in `node_modules/jat-feedback/supabase/migrations/`. Check for new files after upgrading and apply any you haven't run:
+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
-# See what migration files the package ships
+# 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 new ones into your project
+# 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_reports_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
 
 MIT