fi-edback 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +155 -0
  2. package/dist/client.cjs +1088 -0
  3. package/dist/client.d.cts +15 -0
  4. package/dist/client.d.ts +15 -0
  5. package/dist/client.js +1062 -0
  6. package/dist/index.cjs +414 -0
  7. package/dist/index.d.cts +47 -0
  8. package/dist/index.d.ts +47 -0
  9. package/dist/index.js +377 -0
  10. package/package.json +64 -0
package/README.md ADDED
@@ -0,0 +1,155 @@
1
+ # fi-edback
2
+
3
+ Floating visual feedback widget for Next.js preview deployments. Clients click anywhere on the page to drop a pin and leave a message. All submissions go to a shared Neon PostgreSQL database, separated by project slug.
4
+
5
+ **Features**:
6
+
7
+ - ✅ Persistent pins — all feedback visible to everyone
8
+ - ✅ Clickable pins — view message, author, and timestamp
9
+ - ✅ Draggable pins — reposition feedback with mouse or touch
10
+ - ✅ Reactions — engage with feedback using emojis (👍 ✅ ❤️ 🔥 👀)
11
+ - ✅ Delete feedback — anyone can delete (no auth)
12
+ - ✅ IP tracking — automatic fallback identifier
13
+ - ✅ i18n — EN/DE/GA language toggle with visual active state
14
+ - ✅ Mobile-friendly — touch support for dragging, responsive UI
15
+
16
+ ---
17
+
18
+ ## One-time setup checklist
19
+
20
+ - [ ] Create a [Neon](https://neon.tech) project (free tier)
21
+ - [ ] Open the Neon SQL Editor and run `SQL_MIGRATION.sql` to create the `fi_feedback` table
22
+ - [ ] Copy the **pooled** connection string from Neon → Connection Details
23
+
24
+ ---
25
+
26
+ ## Add to a new project
27
+
28
+ ### Install
29
+
30
+ ```bash
31
+ npm i github:Tuffisoft/fi-edback
32
+ npm i @neondatabase/serverless zod
33
+ ```
34
+
35
+ ### 1. Route handler — `app/api/fi-edback/route.ts`
36
+
37
+ ```ts
38
+ import { createFeedbackRouteHandler } from "fi-edback";
39
+ export const { GET, POST, PATCH, DELETE } = createFeedbackRouteHandler();
40
+ ```
41
+
42
+ Provides:
43
+
44
+ - `POST` — submit new feedback
45
+ - `GET` — fetch existing feedback (query: `projectSlug`, `pageUrl`, `sessionId`)
46
+ - `PATCH` — toggle reactions or update pin position
47
+ - `DELETE` — delete feedback by ID (query: `id`)
48
+
49
+ ### 2. Root layout — add `<FeedbackRoot />` inside `<body>`
50
+
51
+ ```tsx
52
+ import { FeedbackRoot } from "fi-edback/client";
53
+
54
+ export default function RootLayout({ children }) {
55
+ return (
56
+ <html>
57
+ <body>
58
+ {children}
59
+ <FeedbackRoot />
60
+ </body>
61
+ </html>
62
+ );
63
+ }
64
+ ```
65
+
66
+ ### 3. Environment variables
67
+
68
+ Set in Vercel → Project Settings → Environment Variables.
69
+ Scope `NEXT_PUBLIC_*` vars to **Preview** only so the widget never appears in production.
70
+
71
+ | Variable | Example | Notes |
72
+ | ----------------------------------- | -------------------------------------- | ------------------------------------------------ |
73
+ | `DATABASE_URL` | `postgresql://...pooler.neon.tech/...` | Neon pooled connection string — server only |
74
+ | `NEXT_PUBLIC_ENABLE_FEEDBACK` | `true` | Widget is hidden unless this is exactly `"true"` |
75
+ | `NEXT_PUBLIC_FEEDBACK_PROJECT_SLUG` | `client-acme` | Tags all rows for this project |
76
+
77
+ ### Per-project checklist
78
+
79
+ - [ ] `npm i github:studiofi/fi-edback`
80
+ - [ ] Create `app/api/fi-edback/route.ts`
81
+ - [ ] Add `<FeedbackRoot />` to root layout
82
+ - [ ] Set `DATABASE_URL` on Vercel (all scopes)
83
+ - [ ] Set `NEXT_PUBLIC_ENABLE_FEEDBACK=true` on Vercel (Preview scope only)
84
+ - [ ] Set `NEXT_PUBLIC_FEEDBACK_PROJECT_SLUG` on Vercel (Preview scope only)
85
+ - [ ] Deploy and test — submit feedback, check Neon table
86
+
87
+ ---
88
+
89
+ ## Disable for production
90
+
91
+ Remove `NEXT_PUBLIC_ENABLE_FEEDBACK` from the Production environment in Vercel.
92
+ The widget renders nothing and no requests are made. No code changes needed.
93
+
94
+ ---
95
+
96
+ ## Development (this repo)
97
+
98
+ ```bash
99
+ # Install root dependencies and build dist/
100
+ npm install
101
+
102
+ # Set up dev environment
103
+ cd dev
104
+ cp .env.local.example .env.local # fill in DATABASE_URL
105
+ npm install
106
+ npm run dev # opens on localhost:3000
107
+ ```
108
+
109
+ ### Dev checklist
110
+
111
+ - [ ] Neon `fi_feedback` table exists (ran `SQL_MIGRATION.sql`)
112
+ - [ ] `dev/.env.local` has `DATABASE_URL`, `NEXT_PUBLIC_ENABLE_FEEDBACK=true`, `NEXT_PUBLIC_FEEDBACK_PROJECT_SLUG=dev`
113
+ - [ ] Dev server running — Feedback button visible bottom-right
114
+ - [ ] Click pin → fill form → submit → row appears in Neon
115
+
116
+ ---
117
+
118
+ ## Upgrade
119
+
120
+ ```bash
121
+ npm update fi-edback
122
+ # or pin a specific commit:
123
+ npm i github:studiofi/fi-edback#<commit-sha>
124
+ ```
125
+
126
+ After upgrading, rebuild if you've modified source:
127
+
128
+ ```bash
129
+ npm run build
130
+ git add dist/
131
+ git commit -m "build: upgrade dist"
132
+ ```
133
+
134
+ ---
135
+
136
+ ## Copilot instructions
137
+
138
+ Drop `.github/instructions/fi-edback-usage.instructions.md` into any consuming project and Copilot will understand the integration automatically:
139
+
140
+ ```bash
141
+ mkdir -p .github/instructions
142
+ cp node_modules/fi-edback/.github/instructions/fi-edback-usage.instructions.md .github/instructions/
143
+ ```
144
+
145
+ ---
146
+
147
+ ## Troubleshooting
148
+
149
+ | Symptom | Cause | Fix |
150
+ | ------------------ | ------------------------------------------- | ------------------------------------- |
151
+ | Button not visible | `NEXT_PUBLIC_ENABLE_FEEDBACK` not `"true"` | Check env vars and restart dev server |
152
+ | Button not visible | `NEXT_PUBLIC_FEEDBACK_PROJECT_SLUG` missing | Set the slug env var |
153
+ | POST returns 500 | `DATABASE_URL` not set | Add server-side env var |
154
+ | POST returns 429 | Rate limit exceeded (5 per 60s per session) | Wait 60 seconds |
155
+ | Hydration error | Old version without mounted guard | `npm update fi-edback` |