Feedback Pulse — Feedback widget and dashboard

A Next.js application for collecting sentiment-annotated user feedback via an embeddable widget and an administrative dashboard.

---

Demo

---

Table of contents

• Quick overview
• Features
• Auth flow and schema
• Widget design and API specifications
• Embedding the widget
• Local development
• Project structure
• How to get an API key
• Security notes
• Contributing
• Deployment

---

Quick overview

• Built with Next.js (App Router), Prisma, and a small auth layer (Better Auth / OAuth).
• Collect feedback via the embeddable widget (public/widget.js) — server validates API keys and performs sentiment analysis using vader-sentiment.
• Admin dashboard and project management lives under app/(dashboard).

---

Features

• Widget: quick embed for external sites (preview in public/widget-test.html).
• Feedback API: stores content, rating (1–5), type (BUG/FEATURE/OTHER), sentiment and score.
• Authentication: email/password + Google OAuth integration.
• Postgres (Prisma) for persistence and included migrations.

---

Auth flow and schema

• Auth implementation: lib/auth.ts (uses better-auth with the Prisma adapter).
• Database schema: prisma/schema.prisma — run pnpm prisma migrate dev to apply changes and pnpm prisma generate to generate the client.
• Important env vars:
  • DATABASE_URL — Postgres connection string
  • NEXTAUTH_URL — app url for OAuth callbacks (e.g. http://localhost:3000)
  • NEXT_PUBLIC_URL — public base URL used to generate embed scripts
  • GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET — for Google OAuth
  • NEXTAUTH_SECRET — session / cookie secret (recommended)

---

Widget design and API specifications

Feedback endpoint

• POST /api/feedback
• Headers:
  • X-API-Key: project API key (required)
  • Content-Type: application/json
• Body (JSON):
  • content (string, required)
  • rating (number, required, 1-5)
  • feedbackType (string, optional: BUG|FEATURE|OTHER)
  • email (string, optional)
• Success: 201 with { success: true, id }
• Errors: 400 (validation), 401 (invalid/missing API key), 500 (server error)

Notes:

• The server runs a quick sentiment analysis (vader-sentiment) and stores sentiment and sentimentScore for each submission.
• CORS on /api/feedback is permissive (allows cross-origin embeds); make sure your API keys remain secret and rotate them if leaked.

Example cURL:

curl -X POST https://your-app.example.com/api/feedback \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"content":"Love the new feature!","rating":5}'

---

Embedding the widget

Create a project in the dashboard, copy the project's API key, then paste the embed script into your site where you want the widget:

<!-- simple embed (generated by dashboard) -->
<script
  src="https:/fedback.akashd.online/widget.js"
  data-project-key="YOUR_API_KEY"
></script>

Or use the generateEmbedScript(apiKey, baseUrl) helper in lib/embed.ts to generate the snippet programmatically.

---

Local development

Prereqs: Node 18+, pnpm, Postgres.

1. Install

pnpm install

2. Create a .env (copy from .env.example if present) and set required variables:

DATABASE_URL="postgres://user:pass@localhost:5432/feedback"
NEXTAUTH_URL=http://localhost:3000
NEXT_PUBLIC_URL=http://localhost:3000
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-secret
NEXTAUTH_SECRET=some-random-secret

Never commit secrets to the repo. Use a .env.example (without secrets) for onboarding.

3. Migrate & generate client

pnpm prisma migrate dev --name init
pnpm prisma generate

4. Run dev server

pnpm dev

Open http://localhost:3000

---

Project structure

• app/ — Next.js routes & pages (App Router)
• components/ — UI and widget components
• public/ — demo images, widget JS, test HTML
• lib/ — helpers: auth.ts, db.ts, embed.ts, utils.ts
• prisma/ — schema & migrations
• actions/ — server/client helpers for auth, projects, feedback

---

How to get an API key (dashboard)

1. Sign in and go to Projects → Create project.
2. Copy the API key from the project page or use the Copy API Key button.
3. Paste the key into the data-project-key attribute in the embed script.

---

Contributing

Contributions are welcome. Open issues or pull requests with focused changes.

---