reflet-sdk 0.1.4 → 0.2.0

package/README.md

@@ -18,22 +18,25 @@ bun add reflet-sdk
 
 ### 1. Get Your API Keys
 
-Go to your Reflet dashboard → Board Settings → API Keys & Widget to generate your keys:
+Go to your Reflet dashboard → Settings → API Keys & Widget to generate your keys:
 
 - **Public Key** (`fb_pub_...`) - Safe to use in frontend code
 - **Secret Key** (`fb_sec_...`) - Keep secure, use only on your server
 
-### 2. Basic Usage (Vanilla JavaScript/TypeScript)
+### 2. Basic Usage (Any JavaScript/TypeScript Environment)
+
+The core SDK works in any JavaScript environment - browser, Node.js, Deno, Bun, or any framework.
 
 ```typescript
 import { Reflet } from 'reflet-sdk';
 
+// Initialize the client
 const reflet = new Reflet({
   publicKey: 'fb_pub_your_key_here',
   user: {
-    id: 'user_123',
-    email: 'jane@example.com',
-    name: 'Jane Doe',
+    id: 'user_123',           // Required: unique user ID from your system
+    email: 'jane@example.com', // Optional: for notifications
+    name: 'Jane Doe',          // Optional: display name
   },
 });
 
@@ -49,7 +52,7 @@ const { feedbackId } = await reflet.create({
   description: 'Would love to have a dark theme option!',
 });
 
-// Vote on feedback
+// Vote on feedback (toggles vote on/off)
 await reflet.vote('feedback_id');
 
 // Add a comment
@@ -59,26 +62,33 @@ await reflet.comment({
 });
 ```
 
-### 3. React Usage
+### 3. React Integration
+
+For React applications, use the provided hooks for a better developer experience.
 
 ```tsx
 import { RefletProvider, useFeedbackList, useVote, useCreateFeedback } from 'reflet-sdk/react';
 
-// Wrap your app with the provider
+// 1. Wrap your app with the provider (do this once at the root)
 function App() {
-  const currentUser = useCurrentUser(); // Your auth system
+  // Get the current user from your authentication system
+  const currentUser = getCurrentUser(); // Replace with your auth logic
 
   return (
     <RefletProvider
       publicKey="fb_pub_your_key_here"
-      user={currentUser}
+      user={currentUser ? {
+        id: currentUser.id,
+        email: currentUser.email,
+        name: currentUser.name,
+      } : undefined}
     >
-      <FeedbackPage />
+      <YourApp />
     </RefletProvider>
   );
 }
 
-// Use hooks in your components
+// 2. Use hooks anywhere in your app
 function FeedbackPage() {
   const { data, isLoading, error } = useFeedbackList({ sortBy: 'votes' });
   const { mutate: vote } = useVote();
@@ -103,39 +113,221 @@ function FeedbackPage() {
 }
 ```
 
-### 4. Server-Side User Signing (Most Secure)
+### 4. Floating Feedback Widget
+
+One component adds a floating button to your app. Opening it screenshots the
+current viewport, lets the user draw on that screenshot, and lets them point at
+an element so the report carries the React component behind it.
+
+```bash
+npx reflet-cli init
+```
+
+Or mount it yourself, once, as the last child of your app shell:
+
+```tsx
+import { RefletFeedback } from 'reflet-sdk/feedback';
 
-For production apps, sign user tokens on your server to prevent spoofing:
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <RefletFeedback publicKey={process.env.NEXT_PUBLIC_REFLET_PUBLIC_KEY} />
+      </body>
+    </html>
+  );
+}
+```
+
+The entry ships its own `"use client"` directive, so a Next.js layout can stay a
+Server Component. With Vite, read the key from
+`import.meta.env.VITE_REFLET_PUBLIC_KEY` and render the widget next to `<App />`.
+
+Every report carries the URL, page title, browser, OS, device, viewport, locale
+and timezone, plus the last 30 console errors and warnings. Pointing at an
+element adds a selector that resolves back to it, the React component stack, and
+the source file and line when the build exposes them (development and preview
+builds do; production builds strip React's debug data).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `publicKey` | `string` | — | Your `fb_pub_…` key. Optional inside `RefletProvider`. |
+| `user` | `RefletUser` | — | Who is reporting. Hides the email field. |
+| `position` | `"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"` | `"bottom-right"` | Which corner the button sits in. |
+| `enabled` | `boolean` | `true` | Render the widget. Gate it to staff or beta users. |
+| `dismissForDays` | `number` | — | Let a reporter hide the launcher in this browser for this many days. |
+| `captureOnOpen` | `boolean` | `true` | Screenshot as soon as the panel opens. |
+| `captureConsole` | `boolean` | `true` | Record console errors and warnings. |
+| `hotkey` | `string \| null` | `null` | Shortcut toggling the panel, e.g. `"mod+shift+f"`. |
+| `theme` | `"auto" \| "light" \| "dark"` | `"auto"` | Colour scheme. |
+| `primaryColor` | `string` | — | Any CSS color for the button and accents. |
+| `offset` | `number` | `20` | Pixels between the button and the viewport edge. |
+| `metadata` | `Record<string, string>` | — | Extra fields merged into every report. |
+| `categories` | `("bug" \| "idea" \| "question")[]` | all three | Category chips to show. |
+| `labels` | `Partial<FeedbackWidgetLabels>` | — | Override any string for i18n. |
+| `onSubmit` | `(result: { feedbackId: string }) => void` | — | Fires after a successful send. |
+
+The panel renders in a shadow root, so your CSS cannot reach it and its CSS
+cannot reach your app. Screenshots are rendered from the DOM rather than through
+`getDisplayMedia`, so users are never asked for a screen-share permission —
+the trade-off is that cross-origin images without CORS headers, iframes and
+canvas content may come out blank.
+
+### 5. Server-Side User Signing (required for voting and commenting)
+
+`user` is a client-asserted identity: the browser can claim to be anyone, so
+the API accepts it only to attribute a report or a survey answer. Voting,
+commenting and subscribing require a token signed on your server with
+`signUser` — anything else is rejected with a 401.
+
+**On your server** (works with any backend: Express, Fastify, Hono, serverless functions, etc.):
 
 ```typescript
-// On your server (Next.js API route, Express, etc.)
 import { signUser } from 'reflet-sdk/server';
 
-export async function getUserToken(user: User) {
+// This function uses Web Crypto API - works in Node.js 18+,
+// Deno, Bun, Cloudflare Workers, Vercel Edge, etc.
+export async function generateUserToken(user: YourUserType) {
   const { token, expiresAt } = await signUser(
     {
-      id: user.id,
-      email: user.email,
-      name: user.name,
-      avatar: user.avatarUrl,
+      id: user.id,        // Required: unique identifier
+      email: user.email,  // Optional
+      name: user.name,    // Optional
+      avatar: user.avatar, // Optional
     },
-    process.env.REFLET_SECRET_KEY!
+    process.env.REFLET_SECRET_KEY! // Your secret key from Reflet dashboard
   );
 
   return { token, expiresAt };
 }
 ```
 
-```tsx
-// On the client
+**On the client** (pass the token from your server):
+
+```typescript
 import { Reflet } from 'reflet-sdk';
 
 const reflet = new Reflet({
   publicKey: 'fb_pub_your_key_here',
-  userToken: tokenFromServer, // JWT from your server
+  userToken: tokenFromServer, // JWT received from your server
+});
+```
+
+---
+
+## Important: What NOT To Do
+
+### Security
+
+```typescript
+// ❌ WRONG: Never expose your secret key in client-side code
+const reflet = new Reflet({
+  publicKey: 'fb_pub_xxx',
+  secretKey: 'fb_sec_xxx', // NEVER DO THIS - secret keys are for servers only
 });
+
+// ❌ WRONG: Never hardcode secret keys
+const token = await signUser(user, 'fb_sec_hardcoded_key');
+
+// ✅ CORRECT: Use environment variables on the server
+const token = await signUser(user, process.env.REFLET_SECRET_KEY!);
 ```
 
+### User Identification
+
+```typescript
+// ❌ WRONG: Don't use unstable or guessable user IDs
+const reflet = new Reflet({
+  publicKey: 'fb_pub_xxx',
+  user: { id: 'user@email.com' }, // Email as ID - can change, easily guessed
+});
+
+// ❌ WRONG: Don't use sequential IDs
+const reflet = new Reflet({
+  publicKey: 'fb_pub_xxx',
+  user: { id: '1' }, // Sequential - easily enumerable
+});
+
+// ✅ CORRECT: Use your system's stable, unique user identifier
+const reflet = new Reflet({
+  publicKey: 'fb_pub_xxx',
+  user: { id: 'usr_a1b2c3d4e5' }, // UUID, CUID, or database ID
+});
+```
+
+### Client Initialization
+
+```typescript
+// ❌ WRONG: Don't create multiple client instances
+function handleVote(id: string) {
+  const reflet = new Reflet({ publicKey: 'fb_pub_xxx' }); // New instance every call
+  await reflet.vote(id);
+}
+
+// ✅ CORRECT: Create one instance and reuse it
+const reflet = new Reflet({ publicKey: 'fb_pub_xxx', user: currentUser });
+
+function handleVote(id: string) {
+  await reflet.vote(id);
+}
+```
+
+### React Provider
+
+```tsx
+// ❌ WRONG: Don't use hooks outside the provider
+function App() {
+  return (
+    <div>
+      <FeedbackList /> {/* Error: No RefletProvider */}
+      <RefletProvider publicKey="fb_pub_xxx">
+        <OtherStuff />
+      </RefletProvider>
+    </div>
+  );
+}
+
+// ✅ CORRECT: Wrap at the root, use hooks inside
+function App() {
+  return (
+    <RefletProvider publicKey="fb_pub_xxx" user={currentUser}>
+      <FeedbackList />
+      <OtherStuff />
+    </RefletProvider>
+  );
+}
+```
+
+### Token Handling
+
+```typescript
+// ❌ WRONG: Don't sign tokens on the client
+import { signUser } from 'reflet-sdk/server';
+// This exposes your secret key in client bundle!
+
+// ❌ WRONG: Don't mix user and userToken
+const reflet = new Reflet({
+  publicKey: 'fb_pub_xxx',
+  user: { id: '123' },
+  userToken: 'jwt_token', // Pick one, not both
+});
+
+// ✅ CORRECT: Use user for simple cases (client-side identification)
+const reflet = new Reflet({
+  publicKey: 'fb_pub_xxx',
+  user: { id: '123', email: 'user@example.com' },
+});
+
+// ✅ CORRECT: Use userToken for production (server-signed)
+const reflet = new Reflet({
+  publicKey: 'fb_pub_xxx',
+  userToken: tokenFromYourServer,
+});
+```
+
+---
+
 ## API Reference
 
 ### `Reflet` Client
@@ -148,63 +340,75 @@ const reflet = new Reflet(config: RefletConfig);
 
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
-| `publicKey` | `string` | Yes | Your board's public API key |
-| `user` | `RefletUser` | No | User information for identification |
-| `userToken` | `string` | No | Signed JWT from your server (alternative to `user`) |
+| `publicKey` | `string` | Yes | Your organization's public API key (`fb_pub_...`) |
+| `user` | `RefletUser` | No | Client-asserted identity — attributes reports only, never grants voting or commenting |
+| `userToken` | `string` | No | Signed JWT from your server (`signUser`), required for voting, commenting and subscribing |
 | `baseUrl` | `string` | No | Custom API endpoint (defaults to Reflet production API) |
 
+> **Note:** Provide either `user` OR `userToken`, not both. With neither, the user can only read feedback and submit anonymous reports. With `user` alone, reports are attributed but voting, commenting and subscribing stay unavailable.
+
 #### Methods
 
-| Method | Description |
-|--------|-------------|
-| `list(params?)` | List feedback with optional filtering |
-| `get(feedbackId)` | Get single feedback with full details |
-| `create(params)` | Submit new feedback |
-| `vote(feedbackId, type?)` | Vote on feedback (toggle) |
-| `comment(params)` | Add a comment |
-| `subscribe(feedbackId)` | Subscribe to updates |
-| `unsubscribe(feedbackId)` | Unsubscribe from updates |
-| `getConfig()` | Get board configuration |
-| `getRoadmap()` | Get roadmap data |
-| `getChangelog(limit?)` | Get changelog entries |
+| Method | Description | Requires User |
+|--------|-------------|---------------|
+| `list(params?)` | List feedback with optional filtering | No |
+| `get(feedbackId)` | Get single feedback with full details | No |
+| `getConfig()` | Get organization configuration | No |
+| `getRoadmap()` | Get roadmap data | No |
+| `getChangelog(limit?)` | Get changelog entries | No |
+| `create(params)` | Submit new feedback | **Yes** |
+| `vote(feedbackId, type?)` | Vote on feedback (toggle) | **Yes** |
+| `comment(params)` | Add a comment | **Yes** |
+| `getComments(feedbackId)` | Get comments for a feedback | No |
+| `subscribe(feedbackId)` | Subscribe to updates | **Yes** |
+| `unsubscribe(feedbackId)` | Unsubscribe from updates | **Yes** |
 
 ### React Hooks
 
-| Hook | Description |
-|------|-------------|
-| `useFeedbackList(options?)` | Fetch feedback list with filters |
-| `useFeedback(feedbackId)` | Fetch single feedback item |
-| `useComments(feedbackId)` | Fetch comments for feedback |
-| `useVote()` | Vote mutation hook |
-| `useCreateFeedback()` | Create feedback mutation hook |
-| `useAddComment()` | Add comment mutation hook |
-| `useSubscription()` | Subscribe/unsubscribe hooks |
-| `useBoardConfig()` | Fetch board configuration |
-| `useRoadmap()` | Fetch roadmap data |
-| `useChangelog(limit?)` | Fetch changelog entries |
+All hooks must be used inside a `<RefletProvider>`.
+
+| Hook | Description | Requires User |
+|------|-------------|---------------|
+| `useFeedbackList(options?)` | Fetch feedback list with filters | No |
+| `useFeedback(feedbackId)` | Fetch single feedback item | No |
+| `useComments(feedbackId)` | Fetch comments for feedback | No |
+| `useOrganizationConfig()` | Fetch organization configuration | No |
+| `useRoadmap()` | Fetch roadmap data | No |
+| `useChangelog(limit?)` | Fetch changelog entries | No |
+| `useVote()` | Vote mutation hook | **Yes** |
+| `useCreateFeedback()` | Create feedback mutation hook | **Yes** |
+| `useAddComment()` | Add comment mutation hook | **Yes** |
+| `useSubscription()` | Subscribe/unsubscribe hooks | **Yes** |
 
 ### Server Utilities
 
-Works in Node.js, Edge runtimes, Cloudflare Workers, and Convex.
+Works in any JavaScript runtime with Web Crypto API support: Node.js 18+, Deno, Bun, Cloudflare Workers, Vercel Edge, AWS Lambda, etc.
 
 ```typescript
 import { signUser, verifyUser } from 'reflet-sdk/server';
 
 // Sign a user token (async - uses Web Crypto API)
-const { token, expiresAt } = await signUser(user, secretKey, expiresInSeconds?);
+const { token, expiresAt } = await signUser(
+  { id: 'user_123', email: 'user@example.com', name: 'Jane' },
+  secretKey,
+  expiresInSeconds // Optional, defaults to 24 hours
+);
 
-// Verify a token (optional - server-side validation)
+// Verify a token (optional - for server-side validation)
 const user = await verifyUser(token, secretKey);
+// Returns user data if valid, null if invalid/expired
 ```
 
+---
+
 ## Types
 
 ```typescript
 interface RefletUser {
-  id: string;
-  email?: string;
-  name?: string;
-  avatar?: string;
+  id: string;       // Required: unique identifier from your system
+  email?: string;   // Optional: used for notifications
+  name?: string;    // Optional: display name
+  avatar?: string;  // Optional: avatar URL
 }
 
 interface FeedbackItem {
@@ -214,14 +418,14 @@ interface FeedbackItem {
   status: FeedbackStatus;
   voteCount: number;
   commentCount: number;
-  hasVoted: boolean;
+  hasVoted: boolean;        // Whether current user voted
   author?: FeedbackAuthor;
   tags: FeedbackTag[];
   createdAt: string;
 }
 
 interface FeedbackDetail extends FeedbackItem {
-  isSubscribed: boolean;
+  isSubscribed: boolean;    // Whether current user is subscribed
   comments: Comment[];
 }
 
@@ -234,111 +438,195 @@ type FeedbackStatus =
   | 'closed';
 ```
 
+---
+
 ## Error Handling
 
-The SDK provides typed errors for better error handling:
+The SDK provides typed errors for precise error handling:
 
 ```typescript
 import { RefletError, RefletAuthError, RefletNotFoundError } from 'reflet-sdk';
 
 try {
-  await reflet.vote('invalid_id');
+  await reflet.vote('feedback_id');
 } catch (error) {
   if (error instanceof RefletNotFoundError) {
+    // Feedback item doesn't exist
     console.log('Feedback not found');
   } else if (error instanceof RefletAuthError) {
-    console.log('Authentication required');
+    // User not identified or invalid token
+    console.log('Please sign in to vote');
   } else if (error instanceof RefletError) {
-    console.log('API error:', error.message);
+    // Other API errors (rate limit, server error, etc.)
+    console.log('Error:', error.message, 'Status:', error.status);
   }
 }
 ```
 
-## Examples
+### Common Error Scenarios
 
-### Feedback Widget Component
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `RefletAuthError` | No signed token provided | Pass a `userToken` from `signUser`; `user` alone cannot vote or comment |
+| `RefletAuthError` | Invalid or expired token | Generate a new token on your server |
+| `RefletNotFoundError` | Invalid feedback ID | Check the ID exists |
+| `RefletError` (403) | Organization is private | Use a secret key or make organization public |
+| `RefletError` (429) | Rate limited | Reduce request frequency |
 
-```tsx
-import { RefletProvider, useFeedbackList, useCreateFeedback, useVote } from 'reflet-sdk/react';
-import { useState } from 'react';
+---
 
-function FeedbackWidget() {
-  const [isOpen, setIsOpen] = useState(false);
-  const { data, refetch } = useFeedbackList({ limit: 5, sortBy: 'votes' });
-  const { mutate: createFeedback, isLoading } = useCreateFeedback();
-  const { mutate: vote } = useVote();
-  const [title, setTitle] = useState('');
+## Framework Integration Examples
 
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    await createFeedback({ title, description: '' });
-    setTitle('');
-    refetch();
-  };
+### Generic Pattern (Any Framework)
 
-  return (
-    <div className="feedback-widget">
-      <button onClick={() => setIsOpen(!isOpen)}>
-        Feedback
-      </button>
-
-      {isOpen && (
-        <div className="feedback-panel">
-          <form onSubmit={handleSubmit}>
-            <input
-              value={title}
-              onChange={(e) => setTitle(e.target.value)}
-              placeholder="What's on your mind?"
-            />
-            <button type="submit" disabled={isLoading}>
-              Submit
-            </button>
-          </form>
-
-          <ul>
-            {data?.items.map((item) => (
-              <li key={item.id}>
-                <button onClick={() => vote({ feedbackId: item.id })}>
-                  {item.voteCount}
-                </button>
-                <span>{item.title}</span>
-              </li>
-            ))}
-          </ul>
-        </div>
-      )}
-    </div>
+```typescript
+// 1. Create a singleton client instance
+// feedback-client.ts
+import { Reflet } from 'reflet-sdk';
+
+let refletInstance: Reflet | null = null;
+
+export function getRefletClient(user?: { id: string; email?: string; name?: string }) {
+  if (!refletInstance || user) {
+    refletInstance = new Reflet({
+      publicKey: process.env.REFLET_PUBLIC_KEY || 'fb_pub_xxx',
+      user,
+    });
+  }
+  return refletInstance;
+}
+
+// 2. Use it anywhere
+const reflet = getRefletClient(currentUser);
+const feedback = await reflet.list();
+```
+
+### Server-Side Token Generation (Any Backend)
+
+```typescript
+// api/reflet-token.ts (or your preferred API route pattern)
+import { signUser } from 'reflet-sdk/server';
+
+export async function handleTokenRequest(authenticatedUser: YourUserType) {
+  // Verify user is authenticated with YOUR auth system first
+  if (!authenticatedUser) {
+    throw new Error('Unauthorized');
+  }
+
+  const { token, expiresAt } = await signUser(
+    {
+      id: authenticatedUser.id,
+      email: authenticatedUser.email,
+      name: authenticatedUser.displayName,
+    },
+    process.env.REFLET_SECRET_KEY!
   );
+
+  return { token, expiresAt };
 }
 ```
 
-### Next.js App Router Integration
+### React with Any State Management
 
 ```tsx
-// app/providers.tsx
-'use client';
-
+// Works with Redux, Zustand, Jotai, MobX, or plain React state
 import { RefletProvider } from 'reflet-sdk/react';
-import { useSession } from 'next-auth/react';
 
-export function Providers({ children }: { children: React.ReactNode }) {
-  const { data: session } = useSession();
+function App() {
+  // Get user from your state management solution
+  const user = useYourAuthHook(); // useSelector, useStore, useAtom, etc.
 
   return (
     <RefletProvider
-      publicKey={process.env.NEXT_PUBLIC_REFLET_KEY!}
-      user={session?.user ? {
-        id: session.user.id,
-        email: session.user.email!,
-        name: session.user.name!,
-      } : undefined}
+      publicKey="fb_pub_xxx"
+      user={user ? { id: user.id, email: user.email, name: user.name } : undefined}
     >
-      {children}
+      <YourApp />
     </RefletProvider>
   );
 }
 ```
 
+### Vanilla JavaScript (No Framework)
+
+```html
+<script type="module">
+  import { Reflet } from 'https://esm.sh/reflet-sdk';
+
+  const reflet = new Reflet({
+    publicKey: 'fb_pub_xxx',
+    user: { id: 'user_123' },
+  });
+
+  // Load and display feedback
+  const { items } = await reflet.list();
+
+  document.getElementById('feedback-list').innerHTML = items
+    .map(item => `
+      <div>
+        <h3>${item.title}</h3>
+        <p>${item.description}</p>
+        <button onclick="vote('${item.id}')">${item.voteCount} votes</button>
+      </div>
+    `)
+    .join('');
+
+  window.vote = async (id) => {
+    await reflet.vote(id);
+    location.reload(); // Simple refresh, or update DOM manually
+  };
+</script>
+```
+
+---
+
+## Troubleshooting
+
+### "Authentication required" error
+
+**Cause:** Trying to vote, comment, or create feedback without user identification.
+
+**Solution:** Provide a server-signed `userToken` when initializing the client:
+
+```typescript
+const reflet = new Reflet({
+  publicKey: 'fb_pub_xxx',
+  user: { id: 'your_user_id' }, // Add this
+});
+```
+
+### "Organization not found" or 404 errors
+
+**Cause:** Invalid public key or organization doesn't exist.
+
+**Solution:**
+1. Verify your public key in Reflet dashboard → Settings → API Keys
+2. Ensure the organization exists and is active
+
+### "Network error" or connection issues
+
+**Cause:** Cannot reach Reflet API.
+
+**Solution:**
+1. Check your internet connection
+2. Verify no firewall/proxy is blocking requests
+3. The SDK connects to `https://harmless-clam-802.convex.site` by default
+
+### Token expired errors
+
+**Cause:** Server-signed token has expired (default: 24 hours).
+
+**Solution:** Generate and send a fresh token from your server:
+
+```typescript
+// On your server
+const { token } = await signUser(user, secretKey, 86400); // 24 hours
+
+// Refresh before expiry or on 401 errors
+```
+
+---
+
 ## License
 
 MIT