@tmls-ai/support 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @tmls/support
+
+Embeddable Timeless support widget — bottom-right report overlay (type /
+severity / screenshot) + ticket thread. Auto-captures context and talks to
+`tmls-support-api`.
+
+## Usage (React)
+
+```tsx
+import { SupportWidget } from '@tmls/support';
+
+<SupportWidget
+  productId="drona"
+  apiUrl="https://support.timeless.app"
+  getToken={() => fetch('/api/support-token').then(r => r.text())}
+  user={{ id, email, name, plan }}
+  accent="#0a84ff"
+  appVersion={import.meta.env.VITE_BUILD}
+  getContext={() => ({ route: location.pathname, config, specs, conversationId })}
+/>
+```
+
+## Usage (any app, Shadow-DOM isolated)
+
+```ts
+import { mountSupportWidget } from '@tmls/support';
+const unmount = mountSupportWidget({ productId, apiUrl, getToken, getContext });
+```
+
+## Host backend contract
+Expose an endpoint that signs a short-lived JWT with the product's
+`JWT_SECRET_<PRODUCT>` (same secret the Worker holds):
+
+```ts
+jwt.sign({ productId: 'drona', userId, email, plan }, JWT_SECRET_DRONA, { expiresIn: '10m' })
+```
+
+The widget never holds a secret; the server trusts the signed token.
+
+## Build
+
+```bash
+npm run build   # → dist/ (ESM + types)
+```
+
+> v1: `src/types.ts` mirrors `tmls-support-api/src/types.ts` — keep in sync.

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import * as react from 'react';
+
+type ReportType = 'bug' | 'question' | 'feedback';
+type Severity = 'blocking' | 'annoying' | 'minor';
+interface Conversation {
+    id: string;
+    ticket_number: number;
+    type: ReportType;
+    severity: Severity;
+    status: 'open' | 'resolved';
+    created_at: string;
+    last_message_at: string;
+}
+interface Message {
+    id: string;
+    author: 'user' | 'agent' | 'system';
+    body: string;
+    created_at: string;
+}
+/** Everything the host product passes to mount the widget. */
+interface SupportWidgetProps {
+    /** Registered product id, e.g. 'drona'. */
+    productId: string;
+    /** tmls-support-api base URL. */
+    apiUrl: string;
+    /** Returns a short-lived signed JWT from the product's own backend. */
+    getToken: () => Promise<string>;
+    /** Identity (purely for display; the server trusts the token, not this). */
+    user?: {
+        id: string;
+        email?: string;
+        name?: string;
+        plan?: string;
+    };
+    /** Accent color for theming (defaults to a neutral blue). */
+    accent?: string;
+    /** Product-specific context attached to every report (DRONA: { config, specs }). */
+    getContext?: () => Record<string, unknown>;
+    /** App version string for the base context. */
+    appVersion?: string;
+}
+
+declare function SupportWidget(props: SupportWidgetProps): react.JSX.Element;
+
+/**
+ * Vanilla mount for any app (React or not). Renders the widget into a Shadow
+ * DOM root so the host's CSS and the widget's CSS can never collide. React apps
+ * can also just render <SupportWidget /> directly.
+ */
+declare function mountSupportWidget(props: SupportWidgetProps): () => void;
+
+export { type Conversation, type Message, type ReportType, type Severity, SupportWidget, type SupportWidgetProps, mountSupportWidget };

package/dist/index.js

@@ -0,0 +1,342 @@
+// src/index.ts
+import { createRoot } from "react-dom/client";
+import { createElement } from "react";
+
+// src/SupportWidget.tsx
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { domToBlob } from "modern-screenshot";
+
+// src/context.ts
+var MAX_ERRORS = 15;
+var errorBuffer = [];
+var installed = false;
+var sessionId = Math.random().toString(36).slice(2);
+function installErrorCapture() {
+  if (installed || typeof window === "undefined") return;
+  installed = true;
+  const push = (s) => {
+    errorBuffer.push(s.slice(0, 300));
+    if (errorBuffer.length > MAX_ERRORS) errorBuffer.shift();
+  };
+  const origError = console.error.bind(console);
+  console.error = (...args) => {
+    push(args.map(String).join(" "));
+    origError(...args);
+  };
+  window.addEventListener("error", (e) => push(`${e.message} @ ${e.filename}:${e.lineno}`));
+  window.addEventListener("unhandledrejection", (e) => push(`unhandledrejection: ${String(e.reason)}`));
+}
+function collectBaseContext(appVersion) {
+  return {
+    route: typeof location !== "undefined" ? location.pathname + location.search : void 0,
+    appVersion,
+    env: void 0,
+    device: typeof navigator !== "undefined" ? navigator.platform : void 0,
+    browser: typeof navigator !== "undefined" ? navigator.userAgent : void 0,
+    viewport: typeof window !== "undefined" ? { w: window.innerWidth, h: window.innerHeight } : void 0,
+    recentErrors: [...errorBuffer],
+    sessionId,
+    ts: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+
+// src/api.ts
+var SupportApi = class {
+  constructor(apiUrl, getToken) {
+    this.apiUrl = apiUrl;
+    this.getToken = getToken;
+  }
+  async auth() {
+    return { Authorization: `Bearer ${await this.getToken()}` };
+  }
+  async createReport(input) {
+    const res = await fetch(`${this.apiUrl}/v1/reports`, {
+      method: "POST",
+      headers: { ...await this.auth(), "Content-Type": "application/json" },
+      body: JSON.stringify(input)
+    });
+    if (!res.ok) throw new Error(`report failed: ${res.status}`);
+    return res.json();
+  }
+  async uploadScreenshot(blob) {
+    const res = await fetch(`${this.apiUrl}/v1/uploads`, {
+      method: "POST",
+      headers: { ...await this.auth(), "Content-Type": blob.type || "image/png" },
+      body: blob
+    });
+    if (!res.ok) throw new Error(`upload failed: ${res.status}`);
+    return (await res.json()).key;
+  }
+  async listConversations() {
+    const res = await fetch(`${this.apiUrl}/v1/conversations`, { headers: await this.auth() });
+    return res.ok ? res.json() : [];
+  }
+  async listMessages(conversationId) {
+    const res = await fetch(`${this.apiUrl}/v1/conversations/${conversationId}/messages`, { headers: await this.auth() });
+    return res.ok ? res.json() : [];
+  }
+  async reply(conversationId, body) {
+    await fetch(`${this.apiUrl}/v1/conversations/${conversationId}/messages`, {
+      method: "POST",
+      headers: { ...await this.auth(), "Content-Type": "application/json" },
+      body: JSON.stringify({ body })
+    });
+  }
+};
+
+// src/SupportWidget.tsx
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var TYPES = [
+  { id: "bug", label: "Bug" },
+  { id: "question", label: "Question" },
+  { id: "feedback", label: "Feedback" }
+];
+var SEVERITIES = [
+  { id: "blocking", label: "Blocking" },
+  { id: "annoying", label: "Annoying" },
+  { id: "minor", label: "Minor" }
+];
+function SupportWidget(props) {
+  const { productId, apiUrl, getToken, accent = "#0a84ff", getContext, appVersion } = props;
+  const api = useMemo(() => new SupportApi(apiUrl, getToken), [apiUrl, getToken]);
+  const [open, setOpen] = useState(false);
+  const [view, setView] = useState("new");
+  const [type, setType] = useState("bug");
+  const [severity, setSeverity] = useState("annoying");
+  const [message, setMessage] = useState("");
+  const [withShot, setWithShot] = useState(true);
+  const [shotPreview, setShotPreview] = useState(null);
+  const [sending, setSending] = useState(false);
+  const [lastTicket, setLastTicket] = useState(null);
+  const [threads, setThreads] = useState([]);
+  const [activeId, setActiveId] = useState(null);
+  const [messages, setMessages] = useState([]);
+  const [reply, setReply] = useState("");
+  useEffect(() => {
+    installErrorCapture();
+  }, []);
+  const captureShot = useCallback(async () => {
+    try {
+      const blob = await domToBlob(document.body, { quality: 0.8, scale: 0.75 });
+      setShotPreview(URL.createObjectURL(blob));
+      captureShot._blob = blob;
+    } catch {
+    }
+  }, []);
+  const submit = useCallback(async () => {
+    if (!message.trim() || sending) return;
+    setSending(true);
+    try {
+      let attachmentKeys = [];
+      const blob = withShot ? captureShot._blob : void 0;
+      if (blob) {
+        try {
+          attachmentKeys = [await api.uploadScreenshot(blob)];
+        } catch {
+        }
+      }
+      const { ticketNumber } = await api.createReport({
+        type,
+        severity,
+        message: message.trim(),
+        context: { base: collectBaseContext(appVersion), product: getContext?.() },
+        attachmentKeys
+      });
+      setLastTicket(ticketNumber);
+      setMessage("");
+      setShotPreview(null);
+      setView("sent");
+    } catch {
+      setLastTicket(null);
+      setView("sent");
+    } finally {
+      setSending(false);
+    }
+  }, [api, type, severity, message, withShot, getContext, appVersion, sending, captureShot]);
+  const openThreads = useCallback(async () => {
+    setThreads(await api.listConversations());
+    setView("threads");
+  }, [api]);
+  const openThread = useCallback(async (id) => {
+    setActiveId(id);
+    setMessages(await api.listMessages(id));
+    setView("thread");
+  }, [api]);
+  const sendReply = useCallback(async () => {
+    if (!reply.trim() || !activeId) return;
+    await api.reply(activeId, reply.trim());
+    setReply("");
+    setMessages(await api.listMessages(activeId));
+  }, [api, reply, activeId]);
+  const chip = (active) => ({
+    padding: "6px 12px",
+    borderRadius: 999,
+    fontSize: 13,
+    cursor: "pointer",
+    border: "1px solid",
+    borderColor: active ? accent : "#3a3a42",
+    background: active ? accent : "transparent",
+    color: active ? "#fff" : "#c8c8d0"
+  });
+  return /* @__PURE__ */ jsxs("div", { style: { position: "fixed", bottom: 20, right: 20, zIndex: 2147483e3, fontFamily: "system-ui, sans-serif" }, children: [
+    open && /* @__PURE__ */ jsxs("div", { style: {
+      position: "absolute",
+      bottom: 60,
+      right: 0,
+      width: 360,
+      maxHeight: 560,
+      background: "#141418",
+      color: "#e8e8ea",
+      border: "0.5px solid rgba(255,255,255,0.12)",
+      borderRadius: 16,
+      boxShadow: "0 16px 48px rgba(0,0,0,0.5)",
+      overflow: "hidden",
+      display: "flex",
+      flexDirection: "column"
+    }, children: [
+      /* @__PURE__ */ jsxs("div", { style: { display: "flex", justifyContent: "space-between", alignItems: "center", padding: "12px 14px", borderBottom: "0.5px solid rgba(255,255,255,0.08)" }, children: [
+        /* @__PURE__ */ jsx("strong", { style: { fontSize: 14 }, children: "Support" }),
+        /* @__PURE__ */ jsxs("div", { style: { display: "flex", gap: 8, fontSize: 12 }, children: [
+          /* @__PURE__ */ jsx("button", { onClick: () => setView("new"), style: tab(view === "new" || view === "sent", accent), children: "New" }),
+          /* @__PURE__ */ jsx("button", { onClick: openThreads, style: tab(view === "threads" || view === "thread", accent), children: "My tickets" })
+        ] })
+      ] }),
+      /* @__PURE__ */ jsxs("div", { style: { padding: 14, overflowY: "auto" }, children: [
+        view === "new" && /* @__PURE__ */ jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 12 }, children: [
+          /* @__PURE__ */ jsx("div", { style: { display: "flex", gap: 8 }, children: TYPES.map((t) => /* @__PURE__ */ jsx("button", { onClick: () => setType(t.id), style: chip(type === t.id), children: t.label }, t.id)) }),
+          /* @__PURE__ */ jsx("div", { style: { display: "flex", gap: 8 }, children: SEVERITIES.map((s) => /* @__PURE__ */ jsx("button", { onClick: () => setSeverity(s.id), style: chip(severity === s.id), children: s.label }, s.id)) }),
+          /* @__PURE__ */ jsx(
+            "textarea",
+            {
+              value: message,
+              onChange: (e) => setMessage(e.target.value),
+              placeholder: "What happened?",
+              rows: 4,
+              style: { width: "100%", background: "rgba(255,255,255,0.05)", color: "#fff", border: "0.5px solid #3a3a42", borderRadius: 10, padding: 10, fontSize: 14, resize: "vertical" }
+            }
+          ),
+          /* @__PURE__ */ jsxs("label", { style: { display: "flex", alignItems: "center", gap: 8, fontSize: 13, color: "#a0a0a8", cursor: "pointer" }, children: [
+            /* @__PURE__ */ jsx("input", { type: "checkbox", checked: withShot, onChange: (e) => {
+              setWithShot(e.target.checked);
+              if (e.target.checked) captureShot();
+              else setShotPreview(null);
+            } }),
+            "Attach a screenshot"
+          ] }),
+          shotPreview && /* @__PURE__ */ jsx("img", { src: shotPreview, alt: "", style: { width: "100%", borderRadius: 8, border: "0.5px solid #3a3a42" } }),
+          /* @__PURE__ */ jsx("button", { onClick: submit, disabled: !message.trim() || sending, style: { ...primary(accent), opacity: !message.trim() || sending ? 0.5 : 1 }, children: sending ? "Sending\u2026" : "Send report" })
+        ] }),
+        view === "sent" && /* @__PURE__ */ jsxs("div", { style: { textAlign: "center", padding: "20px 0" }, children: [
+          lastTicket ? /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsxs("div", { style: { fontSize: 15, fontWeight: 600 }, children: [
+              "Thanks \u2014 ticket #",
+              lastTicket
+            ] }),
+            /* @__PURE__ */ jsx("div", { style: { fontSize: 13, color: "#a0a0a8", marginTop: 6 }, children: "We'll reply here, and email you when we do." })
+          ] }) : /* @__PURE__ */ jsx("div", { style: { fontSize: 14, color: "#ff9f9f" }, children: "Couldn't send \u2014 please try again." }),
+          /* @__PURE__ */ jsx("button", { onClick: () => setView("new"), style: { ...primary(accent), marginTop: 14 }, children: "New report" })
+        ] }),
+        view === "threads" && /* @__PURE__ */ jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 8 }, children: [
+          threads.length === 0 && /* @__PURE__ */ jsx("div", { style: { fontSize: 13, color: "#a0a0a8" }, children: "No tickets yet." }),
+          threads.map((t) => /* @__PURE__ */ jsxs("button", { onClick: () => openThread(t.id), style: { textAlign: "left", background: "rgba(255,255,255,0.04)", border: "0.5px solid #2a2a32", borderRadius: 10, padding: 10, cursor: "pointer", color: "#e8e8ea" }, children: [
+            /* @__PURE__ */ jsxs("div", { style: { fontSize: 13, fontWeight: 600 }, children: [
+              "#",
+              t.ticket_number,
+              " \xB7 ",
+              t.type
+            ] }),
+            /* @__PURE__ */ jsxs("div", { style: { fontSize: 11, color: "#8a8a92", marginTop: 2 }, children: [
+              t.status,
+              " \xB7 ",
+              new Date(t.last_message_at).toLocaleString()
+            ] })
+          ] }, t.id))
+        ] }),
+        view === "thread" && /* @__PURE__ */ jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 10 }, children: [
+          messages.map((m) => /* @__PURE__ */ jsx("div", { style: {
+            alignSelf: m.author === "user" ? "flex-end" : "flex-start",
+            maxWidth: "85%",
+            background: m.author === "user" ? accent : "rgba(255,255,255,0.06)",
+            color: m.author === "user" ? "#fff" : "#e8e8ea",
+            padding: "8px 11px",
+            borderRadius: 12,
+            fontSize: 13
+          }, children: m.body }, m.id)),
+          /* @__PURE__ */ jsxs("div", { style: { display: "flex", gap: 8 }, children: [
+            /* @__PURE__ */ jsx(
+              "input",
+              {
+                value: reply,
+                onChange: (e) => setReply(e.target.value),
+                placeholder: "Reply\u2026",
+                onKeyDown: (e) => e.key === "Enter" && sendReply(),
+                style: { flex: 1, background: "rgba(255,255,255,0.05)", color: "#fff", border: "0.5px solid #3a3a42", borderRadius: 10, padding: "8px 10px", fontSize: 13 }
+              }
+            ),
+            /* @__PURE__ */ jsx("button", { onClick: sendReply, style: primary(accent), children: "Send" })
+          ] })
+        ] })
+      ] })
+    ] }),
+    /* @__PURE__ */ jsx(
+      "button",
+      {
+        onClick: () => {
+          setOpen((o) => !o);
+          if (!open && withShot) captureShot();
+        },
+        "aria-label": "Support",
+        style: {
+          width: 48,
+          height: 48,
+          borderRadius: 999,
+          border: "none",
+          cursor: "pointer",
+          background: accent,
+          color: "#fff",
+          fontSize: 22,
+          boxShadow: "0 4px 16px rgba(0,0,0,0.35)"
+        },
+        children: open ? "\xD7" : "?"
+      }
+    )
+  ] });
+}
+var tab = (active, accent) => ({
+  background: "transparent",
+  border: "none",
+  cursor: "pointer",
+  fontSize: 12,
+  color: active ? accent : "#8a8a92",
+  fontWeight: active ? 700 : 500
+});
+var primary = (accent) => ({
+  background: accent,
+  color: "#fff",
+  border: "none",
+  borderRadius: 10,
+  padding: "10px 14px",
+  fontSize: 14,
+  fontWeight: 600,
+  cursor: "pointer"
+});
+
+// src/index.ts
+function mountSupportWidget(props) {
+  const host = document.createElement("div");
+  host.setAttribute("data-tmls-support", props.productId);
+  document.body.appendChild(host);
+  const shadow = host.attachShadow({ mode: "open" });
+  const mount = document.createElement("div");
+  shadow.appendChild(mount);
+  const root = createRoot(mount);
+  root.render(createElement(SupportWidget, props));
+  return () => {
+    root.unmount();
+    host.remove();
+  };
+}
+export {
+  SupportWidget,
+  mountSupportWidget
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@tmls-ai/support",
+  "version": "0.1.0",
+  "description": "Embeddable Timeless support widget — bottom-right report overlay (type / severity / screenshot) + ticket thread. Auto-captures context, talks to tmls-support-api.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist"],
+  "repository": { "type": "git", "url": "git+https://github.com/tmls-ai/tmls-support-widget.git" },
+  "keywords": ["support", "widget", "timeless", "tmls"],
+  "publishConfig": { "access": "public" },
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "modern-screenshot": "^4.5.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0"
+  }
+}