@rensblitz/customer-instant-feedback-app 3.0.2 → 3.1.1

package/README.md

@@ -1,75 +1,39 @@
-# Customer Instant Feedback App
+# Feedback Module Setup
 
-A React component library for collecting user feedback directly within your application. Uses a centralized Supabase backend with reviewer-based authentication.
+This project integrates the `@rensblitz/customer-instant-feedback-app` npm package to collect in-app feedback from reviewers. Feedback is stored in a **dedicated, separate Supabase project** — not in this project's own database.
 
-## 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)).
+## 1. Environment variables
 
-## Features
+Add the following to `frontend/.env`:
 
-- Capture screenshots with feedback
-- Annotate specific elements
-- Categorize feedback (Bug, UX, Content, Other)
-- Reviewer-based authentication (no anonymous feedback)
-- 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
+```env
+# Feedback module — dedicated Supabase project
+VITE_FEEDBACK_SUPABASE_URL=https://<your-supabase-project>.supabase.co
+VITE_FEEDBACK_SUPABASE_ANON_KEY=<your-anon-key>
 
-## Installation
+# The project ID assigned by projectinablitz (format: short-code_uuid)
+VITE_FEEDBACK_PROJECT_ID=<your-project-id>
 
-In your React project:
-
-```bash
-npm install @rensblitz/customer-instant-feedback-app @supabase/supabase-js react react-dom react-router-dom
+# Set to "true" to enable the feedback widget, "false" to disable it
+VITE_FEEDBACK_ENABLED=true
 ```
 
-Or with yarn:
+These are distinct from the app's own Supabase credentials (`VITE_SUPABASE_URL` / `VITE_SUPABASE_ANON_KEY`), which are used for the app's own auth and data and must remain in `.env` alongside these.
 
-```bash
-yarn add @rensblitz/customer-instant-feedback-app @supabase/supabase-js react react-dom react-router-dom
-```
+> **Note:** Because Vite does not substitute env vars inside pre-bundled npm packages, `configureFeedbackClient()` must be called from within the host project's own source (see section 3). This is what makes the env vars available to the package at runtime.
 
-Or with pnpm:
+**Next.js users:** use `NEXT_PUBLIC_` instead of `VITE_`:
 
-```bash
-pnpm add @rensblitz/customer-instant-feedback-app @supabase/supabase-js react react-dom react-router-dom
+```env
+NEXT_PUBLIC_FEEDBACK_SUPABASE_URL=https://<your-supabase-project>.supabase.co
+NEXT_PUBLIC_FEEDBACK_SUPABASE_ANON_KEY=<your-anon-key>
+NEXT_PUBLIC_FEEDBACK_PROJECT_ID=<your-project-id>
+NEXT_PUBLIC_FEEDBACK_ENABLED=true
 ```
 
-> **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
-
-**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 users:** add type declarations for these env vars. For Vite, in `src/vite-env.d.ts`:
 
 ```typescript
 /// <reference types="vite/client" />
@@ -77,37 +41,37 @@ Get these from Supabase: Project Settings → API. Use the `anon` (public) key.
 interface ImportMetaEnv {
   readonly VITE_FEEDBACK_SUPABASE_URL: string
   readonly VITE_FEEDBACK_SUPABASE_ANON_KEY: string
+  readonly VITE_FEEDBACK_PROJECT_ID: string
+  readonly VITE_FEEDBACK_ENABLED: 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. Installation
 
-### 2. Database migrations
-
-Run these SQL files in your Supabase SQL editor, in order:
+```bash
+npm install @rensblitz/customer-instant-feedback-app
+```
 
-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)
+The package requires these peer dependencies, which are already present in this project:
 
-### 3. Edge Functions (required for admin)
+- `react` ^18
+- `react-dom` ^18
+- `react-router-dom` ^6
+- `@supabase/supabase-js` ^2
 
-The admin UI uses Edge Functions to create/delete reviewers. Deploy them:
+Also import the stylesheet once in the app entry point:
 
-```bash
-# From the package root (e.g. node_modules/@rensblitz/customer-instant-feedback-app)
-supabase functions deploy create-reviewer
-supabase functions deploy delete-reviewer
+```tsx
+import '@rensblitz/customer-instant-feedback-app/style.css'
 ```
 
-Or copy `supabase/functions/` into your Supabase project and deploy.
+---
 
-### 4. Wrap your app
+## 3. App.tsx setup
 
-In your root component (e.g. `App.tsx` or `main.tsx`):
+### Imports
 
 ```tsx
 import {
@@ -115,189 +79,90 @@ import {
   FeedbackProvider,
   FeedbackLoginPage,
   FeedbackReviewPage,
-} from '@rensblitz/customer-instant-feedback-app';
-import '@rensblitz/customer-instant-feedback-app/style.css';
-import { BrowserRouter, Routes, Route } from 'react-router-dom';
-
-const projectId = 'your-project-id';
-
-function App() {
-  return (
-    <FeedbackAuthProvider>
-      <BrowserRouter>
-        <Routes>
-          <Route path="/feedback-login" element={<FeedbackLoginPage />} />
-          <Route path="/feedback" element={<FeedbackReviewPage projectId={projectId} />} />
-          <Route
-            path="/*"
-            element={
-              <FeedbackProvider projectId={projectId} feedbackReviewPath="/feedback">
-                <YourApp />
-              </FeedbackProvider>
-            }
-          />
-        </Routes>
-      </BrowserRouter>
-    </FeedbackAuthProvider>
-  );
-}
+  configureFeedbackClient,
+} from '@rensblitz/customer-instant-feedback-app'
+import '@rensblitz/customer-instant-feedback-app/style.css'
 ```
 
-**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).
-
-**Important:** Always import the CSS file. Without it, the feedback modal has no styles.
-
-### 5. Get your project ID
+### Client configuration (module level, after all imports)
 
-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`.
-
-### 6. Create the first admin
-
-1. Create a user in Supabase: Authentication → Users → Add user (email + password)
-2. Copy the user's UUID
-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** 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
-
-### FeedbackProvider props
+Call this once at module level — outside any component or function — so the package has its Supabase credentials before it initialises:
 
 ```tsx
-<FeedbackProvider
-  projectId="acme-dash_abc123-uuid"  // Required for full functionality
-  enabled={true}
-  rateLimitSeconds={30}
-  validation={{
-    maxCommentLength: 2000,
-    maxNameLength: 100,
-    maxScreenshotSize: 500000,
-  }}
->
-  <YourApp />
-</FeedbackProvider>
+configureFeedbackClient({
+  url: import.meta.env.VITE_FEEDBACK_SUPABASE_URL,
+  anonKey: import.meta.env.VITE_FEEDBACK_SUPABASE_ANON_KEY,
+})
 ```
 
-- **projectId**: The project identifier from the admin UI. If omitted, a warning banner is shown.
-- **enabled**: Toggle the feedback feature on/off.
-- **feedbackReviewPath**: Path to the feedback review page (default: `/feedback`). Used for the "View all" link in the feedback toolbar.
-- **rateLimitSeconds**: Minimum seconds between submissions.
-- **validation**: Input validation limits.
-
-### Rate limiting
-
-```tsx
-<FeedbackProvider projectId="..." rateLimitSeconds={60}>
-  <YourApp />
-</FeedbackProvider>
-```
+### Component tree structure
 
-### Validation
+The full provider/route structure in `App.tsx`:
 
 ```tsx
-<FeedbackProvider
-  projectId="..."
-  validation={{
-    maxCommentLength: 500,
-    maxNameLength: 50,
-    allowScreenshots: true,
-    maxScreenshotSize: 1024 * 1024,
-  }}
->
-  <YourApp />
-</FeedbackProvider>
-```
-
-## Migrations (central Supabase project)
-
-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` – **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)
-
-## TypeScript types
-
-```typescript
-interface ValidationConfig {
-  maxCommentLength?: number;
-  maxNameLength?: number;
-  allowScreenshots?: boolean;
-  maxScreenshotSize?: number;
-}
+function App() {
+  return (
+    <FeedbackAuthProvider>                         {/* outermost — manages reviewer auth state */}
+      <BrowserRouter>
+        <Routes>
 
-interface FeedbackProviderProps {
-  children: React.ReactNode;
-  projectId?: string;
-  enabled?: boolean;
-  rateLimitSeconds?: number;
-  validation?: ValidationConfig;
-  feedbackReviewPath?: string;
-}
+          {/* Feedback-specific routes — rendered outside FeedbackProvider intentionally */}
+          <Route path="/feedback-login" element={<FeedbackLoginPage />} />
+          <Route path="/feedback" element={<FeedbackReviewPage projectId={import.meta.env.VITE_FEEDBACK_PROJECT_ID} />} />
+
+          {/* All app routes — wrapped with FeedbackProvider so the widget appears on every page */}
+          <Route path="*" element={
+            <FeedbackProvider
+              projectId={import.meta.env.VITE_FEEDBACK_PROJECT_ID}
+              rateLimitSeconds={30}
+              enabled={import.meta.env.VITE_FEEDBACK_ENABLED === 'true'}
+              feedbackReviewPath="/feedback"
+            >
+              {/* rest of the app */}
+            </FeedbackProvider>
+          } />
 
-interface FeedbackReviewPageProps {
-  projectId: string;
+        </Routes>
+      </BrowserRouter>
+    </FeedbackAuthProvider>
+  )
 }
 ```
 
-## Development
-
-### Testing the library locally
+### FeedbackProvider props
 
-The `apps/demo/` folder contains a separate app that imports the library like a real consumer would:
+| Prop | Type | Description |
+|---|---|---|
+| `projectId` | `string` | Project ID from projectinablitz. Required for feedback to be stored correctly. |
+| `enabled` | `boolean` | Toggle the widget on/off without redeployment. Driven by `VITE_FEEDBACK_ENABLED`. |
+| `rateLimitSeconds` | `number` | Minimum seconds between submissions per reviewer. |
+| `feedbackReviewPath` | `string` | Path to the review page. Used for the "View all" link in the widget. |
+| `validation` | `object` | Optional. Limits: `maxCommentLength`, `maxNameLength`, `allowScreenshots`, `maxScreenshotSize`. |
 
-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
-   ```
+## 4. Reviewer flow
 
-3. **Run the demo app:**
-   ```bash
-   npm run demo
-   ```
+- Reviewers navigate to `/feedback-login` and sign in with credentials provisioned by an admin.
+- Once logged in, the feedback widget becomes visible on all app pages (wherever `FeedbackProvider` wraps the UI).
+- Reviewers can visit `/feedback` to see all submitted feedback for the project.
 
-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
+## 5. Managing companies, projects, and reviewers
 
-**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
+The operator UI (**projectinablitz**) is a separate application that lives in the package's monorepo (`apps/projectinablitz-frontend`). It is not part of this project. Use it to:
 
-**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)).
+- Create companies and projects (which gives you the `project_id` to use in the env)
+- Provision and manage reviewer accounts
 
-### Building for npm
+---
 
-```bash
-npm run build
-```
+## 6. Toggling feedback off
 
-Builds the library (ESM, CommonJS, TypeScript declarations, CSS).
-
-### Publishing to npm
-
-```bash
-npm publish --access public
-```
+Set `VITE_FEEDBACK_ENABLED=false` in `frontend/.env` and restart the Vite dev server. The widget will not render. All other feedback infrastructure (routes, providers) remains in place but is inert.
 
-The package is configured for npm distribution with proper exports.
+---
 
 ## License