react-linear-feedback 0.1.0

package/dist/server/index.cjs

@@ -0,0 +1,170 @@
+'use strict';
+
+var sdk = require('@linear/sdk');
+
+// src/server/core.ts
+var MAX_NOTE = 5e3;
+async function createFeedbackIssue(payload, config) {
+  const { apiKey, teamId } = config;
+  if (!apiKey || !teamId) throw new Error("not_configured");
+  const note = payload?.annotation?.note?.trim();
+  if (!note) throw new Error("note_required");
+  if (note.length > MAX_NOTE) throw new Error("note_too_long");
+  const { annotation, context } = payload;
+  const typeLabel = annotation.typeLabel || capitalize(annotation.type || "Feedback");
+  const linear = new sdk.LinearClient({ apiKey });
+  let assetUrl = null;
+  if (payload.screenshot?.startsWith("data:image/")) {
+    try {
+      assetUrl = await uploadScreenshot(linear, payload.screenshot);
+    } catch (err) {
+      console.error("[feedback] screenshot upload failed", err);
+    }
+  }
+  const description = [
+    note,
+    "",
+    "---",
+    assetUrl ? `![screenshot](${encodeURI(assetUrl)})` : "_No screenshot captured._",
+    "",
+    "**Context**",
+    `- Type: ${typeLabel}`,
+    context?.url ? `- Page: ${context.url}` : null,
+    annotation.name ? `- Reported by: ${annotation.name}` : null,
+    context?.userAgent ? `- User agent: ${context.userAgent}` : null,
+    context?.timestamp ? `- Submitted: ${context.timestamp}` : null
+  ].filter(Boolean).join("\n");
+  const title = `${typeLabel}: ${note.slice(0, 60)}${note.length > 60 ? "\u2026" : ""}`;
+  const labelName = config.labels?.[annotation.type] ?? annotation.type;
+  const labelId = labelName ? await resolveLabelId(linear, labelName, teamId) : null;
+  if (labelName && !labelId) console.warn(`[feedback] label "${labelName}" not found \u2014 creating issue without it`);
+  const create = async (ids) => {
+    const created = await linear.createIssue({ teamId, title, description, labelIds: ids.length ? ids : void 0 });
+    return await created.issue;
+  };
+  const issue = await create(labelId ? [labelId] : []).catch((err) => {
+    if (!labelId) throw err;
+    console.warn("[feedback] create failed with label, retrying without it", err);
+    return create([]);
+  });
+  return { id: issue?.id, identifier: issue?.identifier, url: issue?.url };
+}
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+async function resolveLabelId(linear, name, teamId) {
+  try {
+    const { nodes } = await linear.issueLabels({ filter: { name: { eqIgnoreCase: name } }, first: 50 });
+    if (nodes.length === 0) return null;
+    if (nodes.length === 1) return nodes[0].id;
+    const scored = await Promise.all(
+      nodes.map(async (n) => {
+        try {
+          const team = await n.team;
+          return { id: n.id, teamId: team?.id ?? null };
+        } catch {
+          return { id: n.id, teamId: null };
+        }
+      })
+    );
+    const pick = scored.find((s) => s.teamId === teamId) ?? scored.find((s) => s.teamId === null) ?? scored[0];
+    return pick.id;
+  } catch (err) {
+    console.warn("[feedback] label lookup failed", name, err);
+    return null;
+  }
+}
+async function uploadScreenshot(linear, dataUrl) {
+  const [meta, b64] = dataUrl.split(",");
+  const contentType = /data:(.*?);base64/.exec(meta)?.[1] ?? "image/jpeg";
+  const bytes = Buffer.from(b64, "base64");
+  const filename = `feedback-${Date.now()}.jpg`;
+  const upload = await linear.fileUpload(contentType, filename, bytes.length);
+  if (!upload.success || !upload.uploadFile) throw new Error("failed to request upload URL");
+  const headers = new Headers();
+  headers.set("Content-Type", contentType);
+  headers.set("Cache-Control", "public, max-age=31536000");
+  upload.uploadFile.headers.forEach(({ key, value }) => headers.set(key, value));
+  const put = await fetch(upload.uploadFile.uploadUrl, { method: "PUT", headers, body: new Uint8Array(bytes) });
+  if (!put.ok) throw new Error(`upload PUT failed: ${put.status}`);
+  return upload.uploadFile.assetUrl;
+}
+
+// src/server/next.ts
+var BAD_REQUEST = /* @__PURE__ */ new Set(["note_required", "note_too_long", "bad_type", "not_configured"]);
+function json(body, status) {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+}
+function createNextRoute(config) {
+  return async function POST(req) {
+    if (config.authorize && !await config.authorize(req)) return json({ error: "unauthorized" }, 404);
+    if (config.allowedOrigin) {
+      const origin = req.headers.get("origin") ?? "";
+      if (origin && origin !== config.allowedOrigin) return json({ error: "forbidden_origin" }, 403);
+    }
+    let payload;
+    try {
+      payload = await req.json();
+    } catch {
+      return json({ error: "bad_json" }, 400);
+    }
+    try {
+      const issue = await createFeedbackIssue(payload, config);
+      return json({ ok: true, ...issue }, 200);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (BAD_REQUEST.has(message)) return json({ error: message }, message === "not_configured" ? 500 : 400);
+      console.error("[feedback] issue create failed", err);
+      return json({ error: "issue_create_failed", message }, 502);
+    }
+  };
+}
+function cookieGate(name, value = "1") {
+  return (req) => {
+    const cookie = req.headers.get("cookie") ?? "";
+    return cookie.split(";").map((c) => c.trim()).some((c) => c === `${name}=${value}`);
+  };
+}
+
+// src/server/node.ts
+var BAD_REQUEST2 = /* @__PURE__ */ new Set(["note_required", "note_too_long", "bad_type", "bad_json", "not_configured"]);
+function send(res, status, body) {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify(body));
+}
+async function readJson(req) {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(Buffer.from(chunk));
+  const raw = Buffer.concat(chunks).toString("utf8");
+  if (!raw) throw new Error("bad_json");
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error("bad_json");
+  }
+}
+function createNodeHandler(config) {
+  return async function handler(req, res) {
+    try {
+      if (config.authorize && !await config.authorize(req)) return send(res, 404, { error: "unauthorized" });
+      if (config.allowedOrigin) {
+        const origin = req.headers.origin ?? "";
+        if (origin && origin !== config.allowedOrigin) return send(res, 403, { error: "forbidden_origin" });
+      }
+      const payload = req.body ?? await readJson(req);
+      const issue = await createFeedbackIssue(payload, config);
+      send(res, 200, { ok: true, ...issue });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (BAD_REQUEST2.has(message)) return send(res, message === "not_configured" ? 500 : 400, { error: message });
+      console.error("[feedback] issue create failed", err);
+      send(res, 502, { error: "issue_create_failed", message });
+    }
+  };
+}
+
+exports.cookieGate = cookieGate;
+exports.createFeedbackIssue = createFeedbackIssue;
+exports.createNextRoute = createNextRoute;
+exports.createNodeHandler = createNodeHandler;

package/dist/server/index.d.cts

@@ -0,0 +1,85 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/** Rectangle in PAGE coordinates: clientX + window.scrollX, clientY + window.scrollY. */
+type FeedbackRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type FeedbackAnnotation = {
+    rect: FeedbackRect;
+    /** The note the user typed. */
+    note: string;
+    /** Selected type id (e.g. "bug" | "improvement"). */
+    type: string;
+    /** Human label for the selected type (e.g. "Bug") — used in the issue title. */
+    typeLabel?: string;
+    /** Optional reporter name (persisted in localStorage). */
+    name?: string;
+};
+type FeedbackContext = {
+    url: string;
+    pathname: string;
+    title: string;
+    viewport: {
+        width: number;
+        height: number;
+        dpr: number;
+    };
+    scroll: {
+        x: number;
+        y: number;
+    };
+    userAgent: string;
+    referrer: string;
+    /** Short CSS-ish path to the element under the annotation — a hint for triage/agents. */
+    elementHint: string | null;
+    timestamp: string;
+};
+/** Body POSTed to the feedback endpoint. */
+type FeedbackPayload = {
+    annotation: FeedbackAnnotation;
+    context: FeedbackContext;
+    /** data:image/jpeg;base64,… or null if capture failed (submission still proceeds). */
+    screenshot: string | null;
+};
+
+type FeedbackServerConfig = {
+    /** Linear personal API key (server-side secret). */
+    apiKey: string;
+    /** Target team UUID. */
+    teamId: string;
+    /**
+     * Map a type id (e.g. "bug") to a Linear label NAME. Defaults to the type id itself, so a type
+     * "bug" looks for a label named "bug". Labels are resolved by name at request time.
+     */
+    labels?: Record<string, string>;
+};
+type CreatedIssue = {
+    id?: string;
+    identifier?: string;
+    url?: string;
+};
+declare function createFeedbackIssue(payload: FeedbackPayload, config: FeedbackServerConfig): Promise<CreatedIssue>;
+
+type NextRouteConfig = FeedbackServerConfig & {
+    /** Restrict to a single site origin (cheap extra; not a hard auth boundary). */
+    allowedOrigin?: string;
+    /** Return false to reject the request (e.g. a cookie/session check). */
+    authorize?: (req: Request) => boolean | Promise<boolean>;
+};
+declare function createNextRoute(config: NextRouteConfig): (req: Request) => Promise<Response>;
+/** Authorize helper: allow only requests carrying `name=value` in the Cookie header. */
+declare function cookieGate(name: string, value?: string): (req: Request) => boolean;
+
+type NodeHandlerConfig = FeedbackServerConfig & {
+    allowedOrigin?: string;
+    authorize?: (req: IncomingMessage) => boolean | Promise<boolean>;
+};
+type NodeReq = IncomingMessage & {
+    body?: unknown;
+};
+declare function createNodeHandler(config: NodeHandlerConfig): (req: NodeReq, res: ServerResponse) => Promise<void>;
+
+export { type CreatedIssue, type FeedbackAnnotation, type FeedbackContext, type FeedbackPayload, type FeedbackRect, type FeedbackServerConfig, type NextRouteConfig, type NodeHandlerConfig, cookieGate, createFeedbackIssue, createNextRoute, createNodeHandler };

package/dist/server/index.d.ts

@@ -0,0 +1,85 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/** Rectangle in PAGE coordinates: clientX + window.scrollX, clientY + window.scrollY. */
+type FeedbackRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type FeedbackAnnotation = {
+    rect: FeedbackRect;
+    /** The note the user typed. */
+    note: string;
+    /** Selected type id (e.g. "bug" | "improvement"). */
+    type: string;
+    /** Human label for the selected type (e.g. "Bug") — used in the issue title. */
+    typeLabel?: string;
+    /** Optional reporter name (persisted in localStorage). */
+    name?: string;
+};
+type FeedbackContext = {
+    url: string;
+    pathname: string;
+    title: string;
+    viewport: {
+        width: number;
+        height: number;
+        dpr: number;
+    };
+    scroll: {
+        x: number;
+        y: number;
+    };
+    userAgent: string;
+    referrer: string;
+    /** Short CSS-ish path to the element under the annotation — a hint for triage/agents. */
+    elementHint: string | null;
+    timestamp: string;
+};
+/** Body POSTed to the feedback endpoint. */
+type FeedbackPayload = {
+    annotation: FeedbackAnnotation;
+    context: FeedbackContext;
+    /** data:image/jpeg;base64,… or null if capture failed (submission still proceeds). */
+    screenshot: string | null;
+};
+
+type FeedbackServerConfig = {
+    /** Linear personal API key (server-side secret). */
+    apiKey: string;
+    /** Target team UUID. */
+    teamId: string;
+    /**
+     * Map a type id (e.g. "bug") to a Linear label NAME. Defaults to the type id itself, so a type
+     * "bug" looks for a label named "bug". Labels are resolved by name at request time.
+     */
+    labels?: Record<string, string>;
+};
+type CreatedIssue = {
+    id?: string;
+    identifier?: string;
+    url?: string;
+};
+declare function createFeedbackIssue(payload: FeedbackPayload, config: FeedbackServerConfig): Promise<CreatedIssue>;
+
+type NextRouteConfig = FeedbackServerConfig & {
+    /** Restrict to a single site origin (cheap extra; not a hard auth boundary). */
+    allowedOrigin?: string;
+    /** Return false to reject the request (e.g. a cookie/session check). */
+    authorize?: (req: Request) => boolean | Promise<boolean>;
+};
+declare function createNextRoute(config: NextRouteConfig): (req: Request) => Promise<Response>;
+/** Authorize helper: allow only requests carrying `name=value` in the Cookie header. */
+declare function cookieGate(name: string, value?: string): (req: Request) => boolean;
+
+type NodeHandlerConfig = FeedbackServerConfig & {
+    allowedOrigin?: string;
+    authorize?: (req: IncomingMessage) => boolean | Promise<boolean>;
+};
+type NodeReq = IncomingMessage & {
+    body?: unknown;
+};
+declare function createNodeHandler(config: NodeHandlerConfig): (req: NodeReq, res: ServerResponse) => Promise<void>;
+
+export { type CreatedIssue, type FeedbackAnnotation, type FeedbackContext, type FeedbackPayload, type FeedbackRect, type FeedbackServerConfig, type NextRouteConfig, type NodeHandlerConfig, cookieGate, createFeedbackIssue, createNextRoute, createNodeHandler };

package/dist/server/index.js

@@ -0,0 +1,165 @@
+import { LinearClient } from '@linear/sdk';
+
+// src/server/core.ts
+var MAX_NOTE = 5e3;
+async function createFeedbackIssue(payload, config) {
+  const { apiKey, teamId } = config;
+  if (!apiKey || !teamId) throw new Error("not_configured");
+  const note = payload?.annotation?.note?.trim();
+  if (!note) throw new Error("note_required");
+  if (note.length > MAX_NOTE) throw new Error("note_too_long");
+  const { annotation, context } = payload;
+  const typeLabel = annotation.typeLabel || capitalize(annotation.type || "Feedback");
+  const linear = new LinearClient({ apiKey });
+  let assetUrl = null;
+  if (payload.screenshot?.startsWith("data:image/")) {
+    try {
+      assetUrl = await uploadScreenshot(linear, payload.screenshot);
+    } catch (err) {
+      console.error("[feedback] screenshot upload failed", err);
+    }
+  }
+  const description = [
+    note,
+    "",
+    "---",
+    assetUrl ? `![screenshot](${encodeURI(assetUrl)})` : "_No screenshot captured._",
+    "",
+    "**Context**",
+    `- Type: ${typeLabel}`,
+    context?.url ? `- Page: ${context.url}` : null,
+    annotation.name ? `- Reported by: ${annotation.name}` : null,
+    context?.userAgent ? `- User agent: ${context.userAgent}` : null,
+    context?.timestamp ? `- Submitted: ${context.timestamp}` : null
+  ].filter(Boolean).join("\n");
+  const title = `${typeLabel}: ${note.slice(0, 60)}${note.length > 60 ? "\u2026" : ""}`;
+  const labelName = config.labels?.[annotation.type] ?? annotation.type;
+  const labelId = labelName ? await resolveLabelId(linear, labelName, teamId) : null;
+  if (labelName && !labelId) console.warn(`[feedback] label "${labelName}" not found \u2014 creating issue without it`);
+  const create = async (ids) => {
+    const created = await linear.createIssue({ teamId, title, description, labelIds: ids.length ? ids : void 0 });
+    return await created.issue;
+  };
+  const issue = await create(labelId ? [labelId] : []).catch((err) => {
+    if (!labelId) throw err;
+    console.warn("[feedback] create failed with label, retrying without it", err);
+    return create([]);
+  });
+  return { id: issue?.id, identifier: issue?.identifier, url: issue?.url };
+}
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+async function resolveLabelId(linear, name, teamId) {
+  try {
+    const { nodes } = await linear.issueLabels({ filter: { name: { eqIgnoreCase: name } }, first: 50 });
+    if (nodes.length === 0) return null;
+    if (nodes.length === 1) return nodes[0].id;
+    const scored = await Promise.all(
+      nodes.map(async (n) => {
+        try {
+          const team = await n.team;
+          return { id: n.id, teamId: team?.id ?? null };
+        } catch {
+          return { id: n.id, teamId: null };
+        }
+      })
+    );
+    const pick = scored.find((s) => s.teamId === teamId) ?? scored.find((s) => s.teamId === null) ?? scored[0];
+    return pick.id;
+  } catch (err) {
+    console.warn("[feedback] label lookup failed", name, err);
+    return null;
+  }
+}
+async function uploadScreenshot(linear, dataUrl) {
+  const [meta, b64] = dataUrl.split(",");
+  const contentType = /data:(.*?);base64/.exec(meta)?.[1] ?? "image/jpeg";
+  const bytes = Buffer.from(b64, "base64");
+  const filename = `feedback-${Date.now()}.jpg`;
+  const upload = await linear.fileUpload(contentType, filename, bytes.length);
+  if (!upload.success || !upload.uploadFile) throw new Error("failed to request upload URL");
+  const headers = new Headers();
+  headers.set("Content-Type", contentType);
+  headers.set("Cache-Control", "public, max-age=31536000");
+  upload.uploadFile.headers.forEach(({ key, value }) => headers.set(key, value));
+  const put = await fetch(upload.uploadFile.uploadUrl, { method: "PUT", headers, body: new Uint8Array(bytes) });
+  if (!put.ok) throw new Error(`upload PUT failed: ${put.status}`);
+  return upload.uploadFile.assetUrl;
+}
+
+// src/server/next.ts
+var BAD_REQUEST = /* @__PURE__ */ new Set(["note_required", "note_too_long", "bad_type", "not_configured"]);
+function json(body, status) {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+}
+function createNextRoute(config) {
+  return async function POST(req) {
+    if (config.authorize && !await config.authorize(req)) return json({ error: "unauthorized" }, 404);
+    if (config.allowedOrigin) {
+      const origin = req.headers.get("origin") ?? "";
+      if (origin && origin !== config.allowedOrigin) return json({ error: "forbidden_origin" }, 403);
+    }
+    let payload;
+    try {
+      payload = await req.json();
+    } catch {
+      return json({ error: "bad_json" }, 400);
+    }
+    try {
+      const issue = await createFeedbackIssue(payload, config);
+      return json({ ok: true, ...issue }, 200);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (BAD_REQUEST.has(message)) return json({ error: message }, message === "not_configured" ? 500 : 400);
+      console.error("[feedback] issue create failed", err);
+      return json({ error: "issue_create_failed", message }, 502);
+    }
+  };
+}
+function cookieGate(name, value = "1") {
+  return (req) => {
+    const cookie = req.headers.get("cookie") ?? "";
+    return cookie.split(";").map((c) => c.trim()).some((c) => c === `${name}=${value}`);
+  };
+}
+
+// src/server/node.ts
+var BAD_REQUEST2 = /* @__PURE__ */ new Set(["note_required", "note_too_long", "bad_type", "bad_json", "not_configured"]);
+function send(res, status, body) {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify(body));
+}
+async function readJson(req) {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(Buffer.from(chunk));
+  const raw = Buffer.concat(chunks).toString("utf8");
+  if (!raw) throw new Error("bad_json");
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error("bad_json");
+  }
+}
+function createNodeHandler(config) {
+  return async function handler(req, res) {
+    try {
+      if (config.authorize && !await config.authorize(req)) return send(res, 404, { error: "unauthorized" });
+      if (config.allowedOrigin) {
+        const origin = req.headers.origin ?? "";
+        if (origin && origin !== config.allowedOrigin) return send(res, 403, { error: "forbidden_origin" });
+      }
+      const payload = req.body ?? await readJson(req);
+      const issue = await createFeedbackIssue(payload, config);
+      send(res, 200, { ok: true, ...issue });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (BAD_REQUEST2.has(message)) return send(res, message === "not_configured" ? 500 : 400, { error: message });
+      console.error("[feedback] issue create failed", err);
+      send(res, 502, { error: "issue_create_failed", message });
+    }
+  };
+}
+
+export { cookieGate, createFeedbackIssue, createNextRoute, createNodeHandler };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "react-linear-feedback",
+  "version": "0.1.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oliverodgaardwastehero/react-linear-feedback.git"
+  },
+  "homepage": "https://github.com/oliverodgaardwastehero/react-linear-feedback#readme",
+  "bugs": {
+    "url": "https://github.com/oliverodgaardwastehero/react-linear-feedback/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "keywords": [
+    "react",
+    "feedback",
+    "linear",
+    "screenshot",
+    "bug-report",
+    "widget"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "require": "./dist/react/index.cjs"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js",
+      "require": "./dist/server/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup && node scripts/postbuild.mjs",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "modern-screenshot": "^4.7.0"
+  },
+  "peerDependencies": {
+    "@linear/sdk": ">=40",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "@linear/sdk": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@linear/sdk": "^86.0.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.0"
+  }
+}