@rensblitz/customer-instant-feedback-app 2.0.4 → 3.0.1

package/README.md

@@ -2,13 +2,20 @@
 
 A React component library for collecting user feedback directly within your application. Uses a centralized Supabase backend with reviewer-based authentication.
 
+## Repository layout (this monorepo)
+
+- **`packages/customer-instant-feedback-app`** — the publishable npm package (`npm run build`, `npm publish -w @rensblitz/customer-instant-feedback-app`).
+- **`apps/demo`** — local consumer app (workspace `file:` link).
+- **`apps/demo-npm`** — same idea, but depends on the **published** package from npm (see `apps/demo-npm/README.md`).
+- **`apps/feedback-admin-app`** — standalone admin UI (deploy from repo root; see [`render.yaml`](./render.yaml)).
+
 ## Features
 
 - Capture screenshots with feedback
 - Annotate specific elements
 - Categorize feedback (Bug, UX, Content, Other)
 - Reviewer-based authentication (no anonymous feedback)
-- Admin UI for managing companies, projects, and reviewers
+- Admin UI is a **standalone app** in [`apps/feedback-admin-app/`](./apps/feedback-admin-app/) (not exported from the npm package in v3+)
 - Feedback review page for reviewers to see all feedback (including from colleagues)
 - Client-side rate limiting
 - Input validation
@@ -35,9 +42,70 @@ pnpm add @rensblitz/customer-instant-feedback-app @supabase/supabase-js react re
 
 > **Note:** React, React DOM, React Router, and Supabase are peer dependencies. If your project already has them, you only need to install the feedback package.
 
+### Upgrading from 2.x to 3.x
+
+- **`FeedbackAdminPage` was removed** from the package. Remove any import and route; use the standalone [`apps/feedback-admin-app`](./apps/feedback-admin-app/) (or deploy it separately).
+- **`getSupabaseClient`** is now exported if you need direct Supabase access in advanced integrations.
+
 ## Quick Start
 
-### 1. Wrap your app
+**Host app integration (typical):** install the package, add Supabase URL + anon key to `.env`, wrap the app with `FeedbackAuthProvider` / `FeedbackProvider`, and pass the `project_id` string from your operator. You do **not** need to run database migrations in your repo—that happens on the Supabase project (see below if you operate that backend). The in-app setup page at `/readme` (`FeedbackReadmePage`) describes only this flow; full operator steps stay in this README.
+
+### 1. Environment variables (host project)
+
+Add these to your **host project's** `.env` file (not this package):
+
+**Vite / Create React App:**
+```
+VITE_FEEDBACK_SUPABASE_URL=https://your-project.supabase.co
+VITE_FEEDBACK_SUPABASE_ANON_KEY=your-anon-key
+```
+
+**Next.js:**
+```
+NEXT_PUBLIC_FEEDBACK_SUPABASE_URL=https://your-project.supabase.co
+NEXT_PUBLIC_FEEDBACK_SUPABASE_ANON_KEY=your-anon-key
+```
+
+Get these from Supabase: Project Settings → API. Use the `anon` (public) key.
+
+**TypeScript users:** Add type definitions for these environment variables. For Vite projects, create `src/vite-env.d.ts`:
+
+```typescript
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_FEEDBACK_SUPABASE_URL: string
+  readonly VITE_FEEDBACK_SUPABASE_ANON_KEY: string
+}
+```
+
+For Next.js, add to `next-env.d.ts` or create a similar declaration file.
+
+Alternatively, call `configureFeedbackClient({ url, anonKey })` at app init.
+
+### 2. Database migrations
+
+Run these SQL files in your Supabase SQL editor, in order:
+
+1. `migrations/schema_central.sql` – Creates tables
+2. `migrations/extend_feedback_items.sql` – **Skip for new installs.** Only run if you already have `feedback_items` from a previous setup; running on a fresh install will fail.
+3. `migrations/rls_central.sql` – RLS policies
+4. `migrations/create_admin.sql` – Creates your first admin (replace placeholder UUID)
+
+### 3. Edge Functions (required for admin)
+
+The admin UI uses Edge Functions to create/delete reviewers. Deploy them:
+
+```bash
+# From the package root (e.g. node_modules/@rensblitz/customer-instant-feedback-app)
+supabase functions deploy create-reviewer
+supabase functions deploy delete-reviewer
+```
+
+Or copy `supabase/functions/` into your Supabase project and deploy.
+
+### 4. Wrap your app
 
 In your root component (e.g. `App.tsx` or `main.tsx`):
 
@@ -46,7 +114,6 @@ import {
   FeedbackAuthProvider,
   FeedbackProvider,
   FeedbackLoginPage,
-  FeedbackAdminPage,
   FeedbackReviewPage,
 } from '@rensblitz/customer-instant-feedback-app';
 import '@rensblitz/customer-instant-feedback-app/style.css';
@@ -60,12 +127,11 @@ function App() {
       <BrowserRouter>
         <Routes>
           <Route path="/feedback-login" element={<FeedbackLoginPage />} />
-          <Route path="/feedback-admin" element={<FeedbackAdminPage />} />
           <Route path="/feedback" element={<FeedbackReviewPage projectId={projectId} />} />
           <Route
             path="/*"
             element={
-              <FeedbackProvider projectId={projectId}>
+              <FeedbackProvider projectId={projectId} feedbackReviewPath="/feedback">
                 <YourApp />
               </FeedbackProvider>
             }
@@ -77,26 +143,24 @@ function App() {
 }
 ```
 
-**Important:** Always import the CSS file. Without it, the feedback modal has no styles.
+**Admin UI** (companies, projects, reviewers) is **not** part of the npm package. Run the standalone app in [`apps/feedback-admin-app/`](./apps/feedback-admin-app/) (see its README) or deploy it separately (e.g. Render).
 
-### 2. Get your project ID
+**Important:** Always import the CSS file. Without it, the feedback modal has no styles.
 
-The `projectId` is created when you add a project in the admin UI (`/feedback-admin`). You must be an admin to access it. After creating a company and project, copy the generated `project_id` (format: `short-code_uuid`) and pass it to `FeedbackProvider`.
+### 5. Get your project ID
 
-### 3. Create the first admin
+Use the **Feedback Admin** standalone app (in `apps/feedback-admin-app/` in this repo) to create a company and project, then copy the `project_id` (format: `short-code_uuid`) and pass it to `FeedbackProvider` and `FeedbackReviewPage`.
 
-Admins are created manually via SQL. In the Supabase SQL editor for the central project:
+### 6. Create the first admin
 
-1. Create a user in Authentication → Users → Add user (email + password)
+1. Create a user in Supabase: Authentication → Users → Add user (email + password)
 2. Copy the user's UUID
-3. Run: `insert into public.admins (user_id) values ('your-user-uuid');`
-
-See `migrations/create_admin.sql` for the template.
+3. Run the SQL from `migrations/create_admin.sql` (replace the placeholder UUID)
 
 ## How it works
 
 - **Reviewers** visit `/feedback-login` to sign in with credentials provided by an admin. Only logged-in reviewers can see and use the feedback widget. They can visit `/feedback` to see all feedback for the project (including from colleagues).
-- **Admins** visit `/feedback-admin` to manage companies, projects, and reviewers. Only users in the `admins` table can access this page.
+- **Admins** use the standalone **Feedback Admin** app (`apps/feedback-admin-app/` in this repository, or your deployed instance) to manage companies, projects, and reviewers. Only users in the `admins` table can access it.
 - **Feedback** is stored in the centralized Supabase project, scoped by project. Each host app passes its `projectId` to identify which project the feedback belongs to.
 
 ## Usage
@@ -127,7 +191,9 @@ See `migrations/create_admin.sql` for the template.
 ### Rate limiting
 
 ```tsx
-<FeedbackProvider projectId="..." rateLimitSeconds={60} />
+<FeedbackProvider projectId="..." rateLimitSeconds={60}>
+  <YourApp />
+</FeedbackProvider>
 ```
 
 ### Validation
@@ -141,15 +207,17 @@ See `migrations/create_admin.sql` for the template.
     allowScreenshots: true,
     maxScreenshotSize: 1024 * 1024,
   }}
-/>
+>
+  <YourApp />
+</FeedbackProvider>
 ```
 
 ## Migrations (central Supabase project)
 
-The package uses a centralized Supabase project. Run these migrations in order:
+Run these migrations in your Supabase SQL editor, in order:
 
 1. `migrations/schema_central.sql` – Creates companies, projects, admins, reviewers, and feedback_items tables
-2. `migrations/extend_feedback_items.sql` – Run only if feedback_items already exists from a previous setup
+2. `migrations/extend_feedback_items.sql` – **Skip for new installs.** Only run if you are upgrading an existing installation that already has a `feedback_items` table from a prior setup. Running on a fresh install will fail.
 3. `migrations/rls_central.sql` – RLS policies
 4. `migrations/create_admin.sql` – Template for creating first admin(s)
 
@@ -179,15 +247,57 @@ interface FeedbackReviewPageProps {
 
 ## Development
 
-### Building the package
+### Testing the library locally
+
+The `apps/demo/` folder contains a separate app that imports the library like a real consumer would:
+
+1. **First time setup:**
+   ```bash
+   npm run demo:install
+   npm link
+   cd demo && npm link @rensblitz/customer-instant-feedback-app
+   ```
+   Add `VITE_FEEDBACK_SUPABASE_URL` and `VITE_FEEDBACK_SUPABASE_ANON_KEY` to `apps/demo/.env` (copy from `apps/demo/.env.example` if present).
+
+2. **Build the library:**
+   ```bash
+   npm run build
+   ```
+
+3. **Run the demo app:**
+   ```bash
+   npm run demo
+   ```
+
+The demo app imports from `node_modules` using `npm link`, so it works exactly like a real host app. 
+
+**After making changes to the library:**
+- Rebuild: `npm run build`
+- The demo will hot-reload automatically
+
+**Demo includes** (typical host routes; see `apps/demo/`):
+- `/feedback-login` - Login page for reviewers
+- `/feedback` - Feedback review page
+- `/readme` - Setup guide (also available as `FeedbackReadmePage` for host apps)
+- `/` - Demo page with the feedback widget
+
+**Admin** is a separate Vite app: run `npm run admin:dev` from the repo root (see [`apps/feedback-admin-app/README.md`](./apps/feedback-admin-app/README.md)).
+
+### Building for npm
 
 ```bash
 npm run build
 ```
 
+Builds the library (ESM, CommonJS, TypeScript declarations, CSS).
+
 ### Publishing to npm
 
-The package is configured for publishing to npm with ESM and CommonJS builds, TypeScript declarations, and CSS styles exported separately.
+```bash
+npm publish --access public
+```
+
+The package is configured for npm distribution with proper exports.
 
 ## License