visual-feedback 0.0.0-stage → 0.1.0

package/docs/recipes/s3.md

@@ -0,0 +1,124 @@
+# Recipe: an S3-compatible bucket (S3, R2, Railway Buckets)
+
+Each report becomes two objects in a private bucket, named and shaped as in the local recipe
+(docs/recipes/local.md): `feedback/<id>/report.json`, whose `image` is the image's name, and
+`feedback/<id>/image.png` or `image.webp`.
+
+The bucket stays private: nothing is public, and people read reports only through your own route,
+behind your own admin check. `report.context` comes from the browser (docs/API.md), so an admin view
+must not show it as proof of who sent a report. The images show the screen as the user saw it, with nothing masked
+(SPEC §7).
+
+## 1. Create the bucket, install, configure
+
+Create the bucket with public access off (on S3, keep Block Public Access on), then check that an
+object URL opened without a key is refused.
+
+```sh
+npm install aws4fetch
+```
+
+Set these on the server. Never send them to the browser.
+
+| variable | for example |
+|---|---|
+| `S3_ENDPOINT` | `https://s3.eu-west-2.amazonaws.com`, `https://<account>.r2.cloudflarestorage.com`, or your Railway Bucket's endpoint |
+| `S3_REGION` | `eu-west-2`; optional, `auto` when unset, which R2 takes and AWS does not |
+| `S3_BUCKET` | `feedback` |
+| `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` | a key that may read and write this bucket only |
+
+## 2. The route
+
+The widget posts to it with `createFeedback({ endpoint: "/api/feedback" })`. This is a Next.js
+App Router route. As written, anyone who can reach `POST` can write to the bucket: before production,
+put it behind your own session check and a rate limit. A report already in the bucket is never
+replaced: the route checks for it first, and every write is create-only (`If-None-Match: *`, which
+S3 and R2 support). On a store that ignores that header, only the first check protects it.
+
+```ts
+// app/api/feedback/route.ts
+import { AwsClient } from "aws4fetch";
+import { FeedbackRequestError, parseFeedbackRequest } from "visual-feedback/server";
+
+// Replace with your own admin check, from your session. Until then, nobody can read.
+async function canRead(_request: Request): Promise<boolean> {
+  return false;
+}
+
+function bucket() {
+  const { S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY } = process.env;
+  if (!S3_ENDPOINT || !S3_BUCKET || !S3_ACCESS_KEY_ID || !S3_SECRET_ACCESS_KEY) {
+    throw new Error("Set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY.");
+  }
+  const client = new AwsClient({
+    accessKeyId: S3_ACCESS_KEY_ID,
+    secretAccessKey: S3_SECRET_ACCESS_KEY,
+    region: S3_REGION || "auto",
+    service: "s3",
+    // aws4fetch retries 5xx about 50 s by default; the user would wait on "Sending…" that long.
+    retries: 2,
+  });
+  const base = `${S3_ENDPOINT.replace(/\/+$/, "")}/${S3_BUCKET}/feedback`;
+  return { client, url: (id: string, name: string) => `${base}/${id}/${name}` };
+}
+
+export async function POST(request: Request): Promise<Response> {
+  try {
+    const { report, image } = await parseFeedbackRequest(request);
+    const { client, url } = bucket();
+    // A report already stored under this id stays: a retry, or a reused id, changes nothing.
+    const stored = await client.fetch(url(report.id, "report.json"), { method: "HEAD" });
+    if (stored.ok) return new Response(null, { status: 204 });
+    // S3 answers 403 for a missing key when the key may not list; any other answer is unclear.
+    if (stored.status !== 403 && stored.status !== 404) {
+      throw new Error(`The bucket answered ${stored.status} for report.json.`);
+    }
+    const name = image ? `image.${image.type === "image/png" ? "png" : "webp"}` : null;
+    // The image first: a report.json in the bucket then always has its image beside it.
+    const puts: [string, BodyInit, string][] = [
+      ...(image && name ? [[name, image, image.type] as [string, BodyInit, string]] : []),
+      ["report.json", JSON.stringify({ ...report, image: name }), "application/json"],
+    ];
+    for (const [file, body, type] of puts) {
+      const put = await client.fetch(url(report.id, file), {
+        method: "PUT",
+        body,
+        // Create-only: S3 and R2 answer 412 and keep the object a request stored first.
+        headers: { "content-type": type, "if-none-match": "*" },
+      });
+      if (!put.ok && put.status !== 412) {
+        throw new Error(`The bucket answered ${put.status} for ${file}.`);
+      }
+    }
+    return new Response(null, { status: 204 });
+  } catch (error) {
+    if (error instanceof FeedbackRequestError) {
+      return new Response(error.message, { status: error.status });
+    }
+    throw error;
+  }
+}
+
+// GET /api/feedback?id=<report id>&file=report.json | image.png | image.webp
+export async function GET(request: Request): Promise<Response> {
+  if (!(await canRead(request))) return new Response(null, { status: 403 });
+  const query = new URL(request.url).searchParams;
+  const id = query.get("id") ?? "";
+  const file = query.get("file") ?? "";
+  // Only a report id and a known file name, so the key cannot leave feedback/<id>/.
+  if (!/^[0-9a-f-]{36}$/.test(id) || !["report.json", "image.png", "image.webp"].includes(file)) {
+    return new Response(null, { status: 400 });
+  }
+  const { client, url } = bucket();
+  const object = await client.fetch(url(id, file));
+  // S3 answers 403, not 404, for a missing key when the key may not list the bucket.
+  const missing = object.status === 403 || object.status === 404;
+  if (!object.ok) return new Response(null, { status: missing ? 404 : 502 });
+  return new Response(object.body, {
+    headers: {
+      "content-type": object.headers.get("content-type") ?? "application/octet-stream",
+      "cache-control": "private, no-store",
+    },
+  });
+}
+```

package/docs/recipes/supabase.md

@@ -0,0 +1,124 @@
+# Recipe: Supabase
+
+Each report becomes one row in a table and, when it has one, one image in the private Storage
+bucket `feedback`, named `<id>/image.png` or `<id>/image.webp`. The row has the Postgres recipe's columns
+(docs/recipes/postgres.md), except that `user_id` is the Supabase user's uuid and the image is in
+Storage instead of `bytea`. Row-level security lets
+only your app's admins read either, and nobody but your server can write.
+
+`user_id` is the proof of who sent a report; `report.context` is not (docs/API.md). The images show
+the screen as the user saw it, with nothing masked (SPEC §7).
+
+## 1. Install and create the table, the bucket and the policies
+
+```sh
+npm install @supabase/supabase-js
+```
+
+Run this in the SQL editor. An admin is a user whose `app_metadata.role` is `admin`. Only your
+server can set it, with the service role:
+`supabase.auth.admin.updateUserById(id, { app_metadata: { role: "admin" } })`. A change, removal
+included, reaches the user's token only at their next sign-in or token refresh (within an hour by
+default). Never use `user_metadata` for this: users can edit their own.
+
+```sql
+create table feedback_reports (
+  id uuid primary key,
+  user_id uuid not null references auth.users (id) on delete cascade,
+  created_at timestamptz not null,
+  report jsonb not null,
+  image_type text
+);
+alter table feedback_reports enable row level security;
+grant select on feedback_reports to authenticated;
+grant all on feedback_reports to service_role;
+create policy "Admins read feedback" on feedback_reports for select to authenticated
+  using ((auth.jwt() -> 'app_metadata' ->> 'role') = 'admin');
+
+insert into storage.buckets (id, name, public) values ('feedback', 'feedback', false);
+create policy "Admins read feedback images" on storage.objects for select to authenticated
+  using (bucket_id = 'feedback' and (auth.jwt() -> 'app_metadata' ->> 'role') = 'admin');
+```
+
+No policy allows an insert, an update or a delete, so only the service role, on your server, writes.
+Deleting a user deletes their rows, which list their report ids, so remove their images under
+`<id>/` first.
+
+Check it: with the anon key, `select` on `feedback_reports` returns an empty list or a permission
+error, never a row, and a download from `feedback` is refused.
+
+An admin screen reads with the admin's own session, never the service role key:
+`from("feedback_reports").select()` for the rows, filtered and paged as the screen needs, and
+`storage.from("feedback").createSignedUrl("<id>/image.png", 60)` for an image, `image.webp` when
+`image_type` is `image/webp`. A signed URL works for anyone who holds it for those 60 seconds: show
+it, never share it.
+
+Set `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` on the server. The service role key bypasses
+row-level security: never send it to the browser.
+
+## 2. The route
+
+The widget posts to it with `createFeedback({ endpoint: "/api/feedback" })`. This is a Next.js
+App Router route. As written, it refuses every send until you fill in `currentUser`; then any
+signed-in user can send, so put a rate limit in front of it before production.
+
+```ts
+// app/api/feedback/route.ts
+import { createClient } from "@supabase/supabase-js";
+import { FeedbackRequestError, parseFeedbackRequest } from "visual-feedback/server";
+
+// Replace with your own session: the signed-in user's Supabase id (a uuid), for example from
+// supabase.auth.getUser() in @supabase/ssr. Until then, nobody can send. Never use report.context.
+async function currentUser(_request: Request): Promise<string | null> {
+  return null;
+}
+
+function supabase() {
+  const { SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY } = process.env;
+  if (!SUPABASE_URL || !SUPABASE_SERVICE_ROLE_KEY) {
+    throw new Error("Set SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY.");
+  }
+  return createClient(SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, {
+    auth: { persistSession: false, autoRefreshToken: false },
+  });
+}
+
+export async function POST(request: Request): Promise<Response> {
+  const user = await currentUser(request);
+  if (!user) return new Response(null, { status: 401 });
+  try {
+    const { report, image } = await parseFeedbackRequest(request);
+    const db = supabase();
+    // The image first, so a row never lacks its image.
+    if (image) {
+      const name = `${report.id}/image.${image.type === "image/png" ? "png" : "webp"}`;
+      const upload = await db.storage
+        .from("feedback")
+        .upload(name, image, { contentType: image.type, upsert: false });
+      // A resend finds its image there (409); the id comes from the browser, so never replace it.
+      const error = upload.error;
+      const stored = error && "statusCode" in error && error.statusCode === "409";
+      if (error && !stored) throw error;
+    }
+    const { image: _, ...stored } = report;
+    // A "Try again" sends the same id, so the row it already wrote stays as it is.
+    const insert = await db.from("feedback_reports").upsert(
+      {
+        id: report.id,
+        user_id: user,
+        created_at: report.createdAt,
+        report: stored,
+        image_type: image?.type ?? null,
+      },
+      { onConflict: "id", ignoreDuplicates: true },
+    );
+    if (insert.error) throw insert.error;
+    return new Response(null, { status: 204 });
+  } catch (error) {
+    if (error instanceof FeedbackRequestError) {
+      return new Response(error.message, { status: error.status });
+    }
+    throw error;
+  }
+}
+```

package/docs/recipes/vercel-blob.md

@@ -0,0 +1,123 @@
+# Recipe: Vercel Blob
+
+Each report becomes private blobs, named and shaped as in the S3 recipe (docs/recipes/s3.md):
+`feedback/<id>/report.json` and `feedback/<id>/image.png` or `image.webp`. People read them only
+through your own route, behind your own admin check. `report.context` comes from the browser
+(docs/API.md), so an admin view must not show it as proof of who sent a report. The images show the
+screen as the user saw it, with nothing masked (SPEC §7).
+
+It uses `fetch` and Vercel Blob's REST API, so it needs no package. The URLs, headers and token
+shape are the ones `@vercel/blob` 2.8.1 sends; if Vercel changes its API, compare with that client.
+
+## 1. Create the store
+
+Create a Blob store with private access in your Vercel project. That sets `BLOB_READ_WRITE_TOKEN`
+on the server. Never send it to the browser. Check it: open
+`https://<store id>.private.blob.vercel-storage.com/feedback/<id>/report.json` without the token,
+where the store id is the part after `vercel_blob_rw_` in the token, and Vercel refuses it.
+
+The route takes images up to 3 MB, so the whole request stays under Vercel's 4.5 MB body limit. A
+larger one is refused with 413 and the widget shows its send error; a smaller `capture.maxWidth`
+(docs/API.md) keeps screenshots under it.
+
+## 2. The route
+
+The widget posts to it with `createFeedback({ endpoint: "/api/feedback" })`. This is a Next.js
+App Router route. As written, anyone who can reach `POST` can write: before production, put it
+behind your own session check and a rate limit.
+
+```ts
+// app/api/feedback/route.ts
+import { FeedbackRequestError, parseFeedbackRequest } from "visual-feedback/server";
+
+// Replace with your own admin check, from your session. Until then, nobody can read.
+async function canRead(_request: Request): Promise<boolean> {
+  return false;
+}
+
+function blob() {
+  const token = process.env.BLOB_READ_WRITE_TOKEN;
+  // A read-write token is vercel_blob_rw_<store id>_<secret>.
+  const store = token?.split("_")[3];
+  if (!token?.startsWith("vercel_blob_rw_") || !store) {
+    throw new Error("Set BLOB_READ_WRITE_TOKEN.");
+  }
+  const auth = { authorization: `Bearer ${token}` };
+  const path = (id: string, name: string) => `feedback/${id}/${name}`;
+  return {
+    // Next.js 14 caches a fetch in a route by default; a cached 404 would hide a stored report.
+    read: (id: string, name: string) =>
+      fetch(`https://${store}.private.blob.vercel-storage.com/${path(id, name)}`, {
+        headers: auth,
+        cache: "no-store",
+      }),
+    async put(id: string, name: string, body: BodyInit, type: string) {
+      const query = new URLSearchParams({ pathname: path(id, name) });
+      const put = await fetch(`https://vercel.com/api/blob/?${query}`, {
+        method: "PUT",
+        body,
+        headers: {
+          ...auth,
+          "x-api-version": "12",
+          "x-vercel-blob-access": "private",
+          "x-content-type": type,
+          "x-add-random-suffix": "0",
+          "x-allow-overwrite": "1",
+        },
+      });
+      if (!put.ok) throw new Error(`Vercel Blob answered ${put.status} for ${name}.`);
+    },
+  };
+}
+
+export async function POST(request: Request): Promise<Response> {
+  try {
+    // Vercel refuses a function request body over 4.5 MB; 3 MB plus the report stays under it.
+    const { report, image } = await parseFeedbackRequest(request, { maxImageBytes: 3_000_000 });
+    const store = blob();
+    // The id comes from the browser: once a report is stored, a later request does not replace it.
+    // Two requests with one id at the same moment still can; the check and the write are separate.
+    const stored = await store.read(report.id, "report.json");
+    await stored.body?.cancel();
+    if (stored.ok) return new Response(null, { status: 204 });
+    // Only a 404 means "not stored"; on any other answer, writing could replace a report.
+    if (stored.status !== 404) {
+      throw new Error(`Vercel Blob answered ${stored.status} for report.json.`);
+    }
+    const name = image ? `image.${image.type === "image/png" ? "png" : "webp"}` : null;
+    // The image first: a report.json then always has its image beside it.
+    if (image && name) await store.put(report.id, name, image, image.type);
+    const json = JSON.stringify({ ...report, image: name });
+    await store.put(report.id, "report.json", json, "application/json");
+    return new Response(null, { status: 204 });
+  } catch (error) {
+    if (error instanceof FeedbackRequestError) {
+      return new Response(error.message, { status: error.status });
+    }
+    throw error;
+  }
+}
+
+// GET /api/feedback?id=<report id>&file=report.json | image.png | image.webp
+export async function GET(request: Request): Promise<Response> {
+  if (!(await canRead(request))) return new Response(null, { status: 403 });
+  const query = new URL(request.url).searchParams;
+  const id = query.get("id") ?? "";
+  const file = query.get("file") ?? "";
+  // Only a report id and a known file name, so the read cannot leave feedback/<id>/.
+  if (!/^[0-9a-f-]{36}$/.test(id) || !["report.json", "image.png", "image.webp"].includes(file)) {
+    return new Response(null, { status: 400 });
+  }
+  const object = await blob().read(id, file);
+  if (!object.ok) {
+    await object.body?.cancel();
+    return new Response(null, { status: object.status === 404 ? 404 : 502 });
+  }
+  return new Response(object.body, {
+    headers: {
+      "content-type": object.headers.get("content-type") ?? "application/octet-stream",
+      "cache-control": "private, no-store",
+    },
+  });
+}
+```

package/package.json

@@ -1,6 +1,100 @@
 {
   "name": "visual-feedback",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A small button lets your users screenshot the page, mark it up and write a note. You receive one report and store it where you want.",
+  "keywords": [
+    "feedback",
+    "bug-report",
+    "screenshot",
+    "annotate",
+    "widget",
+    "react",
+    "nextjs"
+  ],
+  "license": "MIT",
+  "author": "Doru Moraru",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dorumrr/visual-feedback.git"
+  },
+  "homepage": "https://github.com/dorumrr/visual-feedback#readme",
+  "bugs": "https://github.com/dorumrr/visual-feedback/issues",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.mts",
+      "import": "./dist/server.mjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.mts",
+      "import": "./dist/react.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "docs/API.md",
+    "docs/SPEC.md",
+    "docs/THEMING.md",
+    "docs/recipes"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "biome check .",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tests",
+    "test": "vitest run",
+    "test:edge": "deno test --no-config --sloppy-imports tests/server/parse.deno.ts",
+    "test:e2e": "playwright test",
+    "test:react": "playwright test -c tests/react/playwright.config.ts",
+    "test:pack": "playwright test -c tests/pack-smoke/playwright.config.ts",
+    "size": "size-limit",
+    "publint": "publint --strict",
+    "check": "npm run lint && npm run typecheck && npm run build && npm run test && npm run test:edge && npm run test:e2e && npm run test:react && npm run test:pack && npm run size && npm run publint",
+    "prepack": "npm run --silent build -- --logLevel warn",
+    "dev": "node tests/dev.mjs",
+    "demo": "node tests/demo.mjs"
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "^4.13.0",
+    "@biomejs/biome": "^2.5.15",
+    "@electric-sql/pglite": "0.5.8",
+    "@electric-sql/pglite-socket": "^0.2.11",
+    "@playwright/test": "^1.64.0",
+    "@size-limit/preset-small-lib": "^14.2.0",
+    "@supabase/supabase-js": "^2.117.3",
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.3.0",
+    "aws4fetch": "^1.0.20",
+    "next": "^16.4.0",
+    "postgres": "^3.4.9",
+    "publint": "^0.3.25",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "size-limit": "^14.2.0",
+    "tsdown": "^0.23.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@zumer/snapdom": "3.3.0"
+  }
+}