react-linear-feedback 0.1.0 → 0.1.1

package/README.md

@@ -1,31 +1,42 @@
 # react-linear-feedback
 
-A drop-in feedback widget for any React app. A trusted user opens it with `?feedback`, **drags a box** over the page, picks **Bug / Improvement**, writes a note — and it captures an **annotated screenshot** and opens a **Linear issue**.
+[![npm version](https://img.shields.io/npm/v/react-linear-feedback.svg)](https://www.npmjs.com/package/react-linear-feedback) [![license](https://img.shields.io/npm/l/react-linear-feedback.svg)](./LICENSE)
 
-- 🪶 **Framework-agnostic** — Next.js, Vite, Remix, CRA… (no `next` dependency)
-- 🎨 **Self-contained styles** — injected at runtime, themeable with one prop; **no CSS import, no Tailwind, no design system** required
+**A drop-in React feedback widget that turns a drawn box + note into a Linear issue with an annotated screenshot.**
+
+A trusted user opens it with `?feedback`, **drags a box** over the page, picks a type (**Bug / Improvement**), writes a note — and it captures a screenshot and files a Linear issue. Framework-agnostic, self-contained styling, no design system required.
+
+<!-- Demo: record a short GIF and drop it here → ![demo](docs/demo.gif) -->
+> _Draw a box anywhere → type a note → it lands in Linear with the annotated screenshot and page context._
+
+- 🪶 **Themeable in one prop** — no CSS import, no Tailwind, no design system; styles are injected at runtime
+- 🌍 **Works in any React app** — Next.js, Vite, Remix, CRA… (no `next` dependency; `"use client"` is built in)
 - 🖼️ **Annotated screenshots** via [`modern-screenshot`](https://github.com/qq15725/modern-screenshot) (handles Tailwind v4 / `oklch()`)
-- 🏷️ **Labels resolved by name** at request time (recoloring/recreating a label in Linear won't break it), applied best-effort
-- 🔌 Tiny server core + **Next.js & Node/Express adapters**
+- 🏷️ **Labels by name, self-healing** — resolved at request time, so recoloring/recreating a label in Linear won't break it; applied best-effort
+- 🔌 **Tiny server core** + Next.js & Node/Express adapters
+
+## Contents
+
+- [Install](#install) · [Quick start (Next.js)](#quick-start-nextjs) · [Vite / any backend](#use-with-vite--any-react-app) · [Linear setup](#linear-setup) · [Configuration](#configuration) · [Theming](#theming) · [Custom types](#custom-types) · [Security](#security) · [Troubleshooting](#troubleshooting) · [License](#license)
 
 ## Install
 
 ```bash
 npm i react-linear-feedback
-# the server entry needs the Linear SDK:
+# the server entry needs the Linear SDK (optional peer):
 npm i @linear/sdk
 ```
 
-`react` / `react-dom` are peer dependencies. `@linear/sdk` is an optional peer — only needed where you run the server handler.
+`react` / `react-dom` are peer dependencies. `@linear/sdk` is an **optional** peer — only needed wherever you run the server handler. Do [Linear setup](#linear-setup) first to get your API key, team, and labels.
 
-## Quick start — Next.js (App Router)
+## Quick start (Next.js, App Router)
 
 **1. Server route** — `app/api/feedback/route.ts`:
 
 ```ts
 import { createNextRoute, cookieGate } from "react-linear-feedback/server";
 
-export const runtime = "nodejs"; // needs Buffer + the Linear SDK
+export const runtime = "nodejs"; // REQUIRED — uses Buffer to process the screenshot; Edge is not supported
 
 export const POST = createNextRoute({
   apiKey: process.env.LINEAR_API_KEY!,
@@ -34,7 +45,7 @@ export const POST = createNextRoute({
 });
 ```
 
-**2. Mount the widget** once (e.g. in `app/layout.tsx`):
+**2. Mount the widget once** (e.g. in `app/layout.tsx`):
 
 ```tsx
 import { FeedbackGate } from "react-linear-feedback/react";
@@ -49,9 +60,11 @@ export default function RootLayout({ children }) {
 }
 ```
 
-Visit any page with `?feedback` to turn it on (a cookie remembers it). `?feedback=0` turns it off.
+No `"use client"` needed — the package ships it, so you can mount `<FeedbackGate>` straight from a Server Component layout.
+
+**3. Turn it on.** The widget is **hidden by default**. Visit any page with **`?feedback`** (or `?feedback=1`) to enable it; a cookie remembers the choice for 90 days. `?feedback=0` turns it off.
 
-## Quick start — Vite / SPA (separate backend)
+## Use with Vite / any React app
 
 Mount the widget and point it at your backend:
 
@@ -65,42 +78,76 @@ Run the handler on any Node server (Express shown):
 
 ```ts
 import express from "express";
-import { createNodeHandler } from "react-linear-feedback/server";
+import cors from "cors";
+import { createNodeHandler, cookieGate } from "react-linear-feedback/server";
 
 const app = express();
+// If the app and API are on different origins, CORS is required or the fetch is blocked:
+app.use("/feedback", cors({ origin: "https://your-site.com", credentials: true }));
 app.post("/feedback", createNodeHandler({
   apiKey: process.env.LINEAR_API_KEY!,
   teamId: process.env.LINEAR_TEAM_ID!,
+  authorize: cookieGate("wh_feedback"), // optional — omit to leave the endpoint open
 }));
 app.listen(8787);
 ```
 
-(Enable CORS for your site origin if the API is on a different host.)
+The handler reads the raw body itself, so it works with or without `express.json()`.
+
+## Linear setup
+
+You need three things from Linear:
+
+1. **API key** — Linear → **Settings → Security & access → Personal API keys** → create one. Keep it server-side as `LINEAR_API_KEY`.
+2. **Team UUID** — the team issues land in. Find it via the Linear API (`viewer`/`teams` query) or your team settings; set it as `LINEAR_TEAM_ID`.
+3. **Labels** — each feedback type is matched to a Linear label **by name** (case-insensitive). With the defaults, make sure labels named **`bug`** and **`improvement`** exist in that team (or workspace). Missing labels don't fail the issue — it's just created without one. Remap names with the server [`labels`](#configuration) option.
+
+```bash
+# .env.local
+LINEAR_API_KEY=lin_api_...
+LINEAR_TEAM_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
 
 ## Configuration
 
-**`<FeedbackGate>` / `<FeedbackWidget>` props**
+### Widget props (`<FeedbackGate>` / `<FeedbackWidget>`)
+
+Most apps only set `brandColor` and maybe `endpoint`.
 
 | Prop | Default | Description |
 | --- | --- | --- |
 | `endpoint` | `/api/feedback` | Where the widget POSTs |
-| `brandColor` | indigo | FAB / active / focus color (sets `--lfb-brand`) |
+| `brandColor` | `#6366f1` | FAB / active / focus color (sets the `--lfb-brand` CSS var) |
 | `position` | `bottom-right` | `bottom-right` \| `bottom-left` \| `top-right` \| `top-left` |
 | `types` | Bug, Improvement | `{ id, label, color, icon? }[]` shown in the composer |
-| `nameRequired` | `true` | Ask for a reporter name before the first submission |
+| `nameRequired` | `true` | Ask for a reporter name before the first submission (saved to localStorage, included in the issue) |
+| `nameStorageKey` | `wh_feedback_name` | localStorage key for the remembered name |
 | `fabLabel` | `Give feedback` | Floating button text |
-| `urlParam` | `feedback` | Toggle param (gate only) |
-| `cookieName` | `wh_feedback` | Enabled-state cookie (gate only) |
+| `urlParam` ¹ | `feedback` | Toggle param |
+| `cookieName` ¹ | `wh_feedback` | Enabled-state cookie name |
+| `cookieValue` ¹ | `1` | Cookie value when enabled |
+| `cookieMaxAgeSeconds` ¹ | `7776000` (90d) | Cookie lifetime |
 
-**Server config** (`createNextRoute` / `createNodeHandler` / `createFeedbackIssue`)
+¹ `<FeedbackGate>` only.
+
+### Server config (`createNextRoute` / `createNodeHandler` / `createFeedbackIssue`)
 
 | Field | Description |
 | --- | --- |
 | `apiKey` | Linear personal API key (**server-side only**) |
 | `teamId` | Target team UUID |
-| `labels` | Optional `{ [typeId]: labelName }` map. Default: the type id is the label name (so `bug` → label `bug`) |
-| `allowedOrigin` | Optional single-origin allowlist |
-| `authorize(req)` | Optional gate; return `false` to reject (`cookieGate` provided) |
+| `labels` | Optional `{ [typeId]: labelName }` map. Default: the type id **is** the label name (so type `bug` → label `bug`) |
+| `allowedOrigin` | Optional single-origin allowlist (adapters) |
+| `authorize(req)` | Optional gate; return `false` to reject. `cookieGate(name, value="1")` is provided |
+
+Remap type ids to differently-named Linear labels:
+
+```ts
+createNextRoute({
+  apiKey, teamId,
+  labels: { bug: "bug", idea: "feature-request" },
+});
+```
 
 ## Theming
 
@@ -118,14 +165,31 @@ Set `brandColor`, or override any CSS variable on `.lfb-doc-layer, .lfb-fixed-la
 />
 ```
 
-Each `type.id` is matched to a Linear label of the same name (or remap via the server `labels` config).
+Each `type.id` is matched to a Linear label of the same name. If your label is named differently, map it on the server via `labels` (above). Built-in `icon` values: `"bug"`, `"improvement"`, `"dot"`.
 
 ## Security
 
-The endpoint **creates Linear issues**, so it's effectively write access to your tracker. It's gated only by what you wire up — use `authorize` (e.g. `cookieGate`, a session check) and/or `allowedOrigin`, and add rate limiting if the page is public. Your `LINEAR_API_KEY` stays server-side; the package never ships it to the browser.
+⚠️ **The endpoint creates Linear issues**, so it's effectively write access to your tracker, and it's **open by default**. Before shipping on a public page:
 
-> Linear asset URLs (the screenshots) are **private** — they render inside the issue but a fresh signed URL is needed to fetch them elsewhere.
+- **Gate it** with `authorize` (e.g. `cookieGate`, or your own session check).
+- **Restrict origin** with `allowedOrigin: "https://your-site.com"`.
+- **Rate-limit** if the page is public (e.g. per-IP).
+
+Your `LINEAR_API_KEY` stays server-side; the package never ships it to the browser. Screenshots are uploaded to Linear's **private** asset storage — they render inside the issue, but the URL needs a fresh signed token to fetch elsewhere (it can't be hot-linked). If a screenshot upload fails, the issue is still created without it.
+
+## Troubleshooting
+
+Submissions never throw in the UI — failures are logged to the browser console with a `[feedback]` prefix, and server errors return a JSON `message`. If issues aren't being created, check:
+
+- `endpoint` points at your route, and `LINEAR_API_KEY` / `LINEAR_TEAM_ID` are set.
+- **CORS** is configured when the app and API are on different origins.
+- `runtime = "nodejs"` is set on the Next.js route (Edge has no `Buffer`).
+- The expected Linear **labels exist** (otherwise the issue is created without a label, with a warning).
 
 ## License
 
-MIT
+MIT — see [LICENSE](./LICENSE).
+
+## Contributing
+
+Issues and PRs welcome at [github.com/oliverodgaardwastehero/react-linear-feedback](https://github.com/oliverodgaardwastehero/react-linear-feedback).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-linear-feedback",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Drop-in React feedback widget: draw a box, write a note, and it captures a screenshot and opens a Linear issue. Framework-agnostic, self-contained styles, zero design-system dependencies.",
   "license": "MIT",
   "author": "Oliver Odgaard",