@verbumia/feedback 0.1.0

package/dist/react/index.cjs

@@ -0,0 +1,644 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react/index.ts
+var react_exports = {};
+__export(react_exports, {
+  FeedbackClient: () => FeedbackClient,
+  FeedbackError: () => FeedbackError,
+  FeedbackPanel: () => FeedbackPanel,
+  feedbackPlugin: () => feedbackPlugin,
+  hasKeyRegistry: () => hasKeyRegistry,
+  resolveKeys: () => resolveKeys
+});
+module.exports = __toCommonJS(react_exports);
+
+// src/react/plugin.tsx
+var import_react_dom = require("react-dom");
+var import_react2 = require("react");
+
+// src/core/types.ts
+var FeedbackError = class extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "FeedbackError";
+  }
+  status;
+  code;
+};
+
+// src/core/tos.ts
+var SDK_TOS_VERSION = "2026-05-18";
+
+// src/core/client.ts
+var SDK_LIB = "@verbumia/feedback";
+var SDK_VER = "0.1.0";
+var FeedbackClient = class {
+  cfg;
+  fetchImpl;
+  tokens = null;
+  queue = [];
+  timer = null;
+  bootstrapping = null;
+  constructor(config) {
+    this.cfg = {
+      flushDebounceMs: 1500,
+      maxBatch: 20,
+      ...config
+    };
+    const f = config.fetchImpl ?? globalThis.fetch;
+    if (!f) {
+      throw new FeedbackError(
+        "no fetch implementation available; pass config.fetchImpl"
+      );
+    }
+    this.fetchImpl = f.bind(globalThis);
+  }
+  base() {
+    return this.cfg.apiBase.replace(/\/+$/, "");
+  }
+  get endUserId() {
+    return this.tokens?.end_user_id ?? this.cfg.endUserId;
+  }
+  get hasConsented() {
+    return this.tokens !== null;
+  }
+  /** Server-minted sessionId / grouping_key (from the token bundle).
+   * Available only after `acceptTos()`; never client-generated. */
+  get sessionId() {
+    return this.tokens?.grouping_key;
+  }
+  /** BCP-47 language the widget is rating strings in. */
+  get language() {
+    return this.cfg.language;
+  }
+  /** ToS version the end user is asked to accept — the SDK's
+   * build-time constant (task 616). NOT integrator/server set. */
+  get tosVersion() {
+    return SDK_TOS_VERSION;
+  }
+  /**
+   * Accept the ToS and bootstrap a scoped token. Idempotent: a second call
+   * returns the in-flight / existing bundle rather than re-accepting.
+   */
+  async acceptTos() {
+    if (this.tokens) return this.tokens;
+    if (this.bootstrapping) return this.bootstrapping;
+    this.bootstrapping = (async () => {
+      const res = await this.fetchImpl(`${this.base()}/v1/feedback/tos`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          // NO grouping_key: server-minted (task 599). It comes back in
+          // the token bundle and is bound into the JWT server-side.
+          project_id: this.cfg.projectId,
+          end_user_id: this.cfg.endUserId,
+          tos_version: SDK_TOS_VERSION,
+          locale: this.cfg.locale
+        })
+      });
+      if (!res.ok) throw await this.problem(res, "tos acceptance failed");
+      this.tokens = await res.json();
+      return this.tokens;
+    })();
+    try {
+      return await this.bootstrapping;
+    } finally {
+      this.bootstrapping = null;
+    }
+  }
+  async refresh() {
+    if (!this.tokens) throw new FeedbackError("not consented");
+    const res = await this.fetchImpl(
+      `${this.base()}/v1/feedback/token/refresh`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ refresh_token: this.tokens.refresh_token })
+      }
+    );
+    if (!res.ok) {
+      this.tokens = null;
+      throw await this.problem(res, "token refresh failed");
+    }
+    this.tokens = await res.json();
+  }
+  /** Authenticated fetch with a single transparent refresh-on-401 retry. */
+  async authed(path, init, retry = true) {
+    if (!this.tokens) await this.acceptTos();
+    const res = await this.fetchImpl(`${this.base()}${path}`, {
+      ...init,
+      headers: {
+        ...init.headers ?? {},
+        Authorization: `Bearer ${this.tokens.access_token}`
+      }
+    });
+    if (res.status === 401 && retry) {
+      await this.refresh();
+      return this.authed(path, init, false);
+    }
+    return res;
+  }
+  /** Strings rendered on the current view, with this end user's prior rating. */
+  async getStrings(opts) {
+    const qs = new URLSearchParams({ language: this.cfg.language });
+    if (opts?.keys?.length) {
+      qs.set("keys", opts.keys.map((k) => `${k.namespace}:${k.key}`).join(","));
+    }
+    if (opts?.namespace) qs.set("namespace", opts.namespace);
+    if (opts?.limit) qs.set("limit", String(opts.limit));
+    const res = await this.authed(`/v1/feedback/strings?${qs}`, {
+      method: "GET"
+    });
+    if (!res.ok) throw await this.problem(res, "failed to load strings");
+    return await res.json();
+  }
+  /** Queue a rating; flushed on debounce or when the batch fills. */
+  rate(payload) {
+    this.enqueue({ kind: "rating", payload });
+  }
+  /** Queue a suggestion; flushed on debounce or when the batch fills. */
+  suggest(payload) {
+    this.enqueue({ kind: "suggestion", payload });
+  }
+  enqueue(item) {
+    this.queue.push(item);
+    if (this.queue.length >= this.cfg.maxBatch) {
+      void this.flush();
+      return;
+    }
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => void this.flush(), this.cfg.flushDebounceMs);
+  }
+  /**
+   * Flush queued items. Best-effort: a transport/auth failure re-queues the
+   * batch once and swallows the error so the host app never sees a throw.
+   */
+  async flush() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (!this.queue.length) return;
+    const batch = this.queue;
+    this.queue = [];
+    const ratings = batch.filter((b) => b.kind === "rating").map((b) => b.payload);
+    const suggestions = batch.filter((b) => b.kind === "suggestion").map((b) => b.payload);
+    try {
+      if (ratings.length) {
+        await this.postBatch("/v1/feedback/ratings", { ratings });
+      }
+      if (suggestions.length) {
+        await this.postBatch("/v1/feedback/suggestions", { suggestions });
+      }
+    } catch {
+      this.queue.unshift(...batch);
+    }
+  }
+  async postBatch(path, body) {
+    const res = await this.authed(path, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-SDK": `${SDK_LIB}@${SDK_VER}` },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) throw await this.problem(res, "batch post failed");
+    return await res.json();
+  }
+  async problem(res, fallback) {
+    let code;
+    let detail = fallback;
+    try {
+      const body = await res.json();
+      code = body.code;
+      if (body.detail) detail = body.detail;
+    } catch {
+    }
+    return new FeedbackError(detail, res.status, code);
+  }
+};
+
+// src/react/panel.tsx
+var import_react = require("react");
+
+// src/core/keys.ts
+var REGISTRY_GLOBAL = "__verbumia_key_registry__";
+function getRegistry() {
+  const g = globalThis;
+  const reg = g[REGISTRY_GLOBAL];
+  if (reg && typeof reg.snapshot === "function") {
+    return reg;
+  }
+  return null;
+}
+function hasKeyRegistry() {
+  return getRegistry() !== null;
+}
+function resolveKeys(explicit) {
+  if (explicit && explicit.length) return dedupe(explicit);
+  const reg = getRegistry();
+  if (reg) return dedupe(reg.snapshot());
+  return [];
+}
+function dedupe(keys) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const k of keys) {
+    const id = `${k.namespace}:${k.key}`;
+    if (!seen.has(id)) {
+      seen.add(id);
+      out.push(k);
+    }
+  }
+  return out;
+}
+
+// src/react/panel.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var C = {
+  bg: "#0b0f0e",
+  panel: "#111714",
+  border: "#1f2a25",
+  text: "#e7f5ef",
+  dim: "#8aa79b",
+  emerald: "#10b981",
+  emeraldSoft: "#34d399"
+};
+function FeedbackPanel(props) {
+  const { client, keys, onClose } = props;
+  const [consented, setConsented] = (0, import_react.useState)(client.hasConsented);
+  const [busy, setBusy] = (0, import_react.useState)(false);
+  const [error, setError] = (0, import_react.useState)(null);
+  const [strings, setStrings] = (0, import_react.useState)([]);
+  const loadStrings = (0, import_react.useCallback)(async () => {
+    setBusy(true);
+    setError(null);
+    try {
+      const resolved = resolveKeys(keys);
+      const res = await client.getStrings({
+        keys: resolved.length ? resolved : void 0
+      });
+      setStrings(res.strings);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Failed to load strings");
+    } finally {
+      setBusy(false);
+    }
+  }, [client, keys]);
+  (0, import_react.useEffect)(() => {
+    if (consented) void loadStrings();
+  }, [consented, loadStrings]);
+  const accept = (0, import_react.useCallback)(async () => {
+    setBusy(true);
+    setError(null);
+    try {
+      await client.acceptTos();
+      setConsented(true);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Could not accept the terms");
+    } finally {
+      setBusy(false);
+    }
+  }, [client]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "div",
+    {
+      role: "dialog",
+      "aria-label": "Translation feedback",
+      style: {
+        position: "fixed",
+        inset: 0,
+        zIndex: 2147483600,
+        background: "rgba(0,0,0,.55)",
+        display: "flex",
+        justifyContent: "flex-end"
+      },
+      onClick: onClose,
+      children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+        "div",
+        {
+          onClick: (e) => e.stopPropagation(),
+          style: {
+            width: "min(420px, 100%)",
+            height: "100%",
+            background: C.bg,
+            color: C.text,
+            borderLeft: `1px solid ${C.border}`,
+            display: "flex",
+            flexDirection: "column",
+            fontFamily: "system-ui, sans-serif"
+          },
+          children: [
+            /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+              "header",
+              {
+                style: {
+                  padding: "16px 18px",
+                  borderBottom: `1px solid ${C.border}`,
+                  display: "flex",
+                  justifyContent: "space-between",
+                  alignItems: "center"
+                },
+                children: [
+                  /* @__PURE__ */ (0, import_jsx_runtime.jsx)("strong", { style: { color: C.emeraldSoft }, children: "Translation feedback" }),
+                  /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+                    "button",
+                    {
+                      type: "button",
+                      onClick: onClose,
+                      "aria-label": "Close",
+                      style: {
+                        background: "transparent",
+                        color: C.dim,
+                        border: "none",
+                        fontSize: 20,
+                        cursor: "pointer"
+                      },
+                      children: "\xD7"
+                    }
+                  )
+                ]
+              }
+            ),
+            /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { padding: 18, overflowY: "auto", flex: 1 }, children: [
+              error && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: { color: "#f87171", fontSize: 13 }, children: error }),
+              !consented ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+                ConsentStep,
+                {
+                  version: client.tosVersion,
+                  busy,
+                  onAccept: accept
+                }
+              ) : busy && !strings.length ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: { color: C.dim }, children: "Loading\u2026" }) : !strings.length ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: { color: C.dim }, children: "No strings to review on this view." }) : strings.map((s) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(StringRow, { s, client }, `${s.namespace}:${s.key}`))
+            ] }),
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+              "footer",
+              {
+                style: {
+                  padding: "10px 18px",
+                  borderTop: `1px solid ${C.border}`,
+                  color: C.dim,
+                  fontSize: 11
+                },
+                children: "Powered by Verbumia"
+              }
+            )
+          ]
+        }
+      )
+    }
+  );
+}
+function ConsentStep(props) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: { lineHeight: 1.5, fontSize: 14 }, children: "Help improve the translations in this app. Your ratings and suggestions are sent to the app owner via Verbumia. Don\u2019t submit personal or sensitive information." }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "button",
+      {
+        type: "button",
+        disabled: props.busy,
+        onClick: props.onAccept,
+        style: {
+          marginTop: 12,
+          width: "100%",
+          background: C.emerald,
+          color: "#03110c",
+          border: "none",
+          borderRadius: 8,
+          padding: "12px 14px",
+          fontWeight: 700,
+          cursor: props.busy ? "default" : "pointer",
+          opacity: props.busy ? 0.6 : 1
+        },
+        children: props.busy ? "\u2026" : `I accept the terms${props.version ? ` (v${props.version})` : ""}`
+      }
+    )
+  ] });
+}
+function StringRow(props) {
+  const { s, client } = props;
+  const [mine, setMine] = (0, import_react.useState)(s.my_rating);
+  const [showSuggest, setShowSuggest] = (0, import_react.useState)(false);
+  const [text, setText] = (0, import_react.useState)("");
+  const [sent, setSent] = (0, import_react.useState)(false);
+  const rate = (stars) => {
+    setMine(stars);
+    client.rate({
+      namespace: s.namespace,
+      key: s.key,
+      language: client.language,
+      translation_hash: s.translation_hash,
+      stars
+    });
+  };
+  const submitSuggestion = () => {
+    if (!text.trim()) return;
+    client.suggest({
+      namespace: s.namespace,
+      key: s.key,
+      language: client.language,
+      translation_hash: s.translation_hash,
+      suggested_text: text.trim()
+    });
+    setSent(true);
+    setShowSuggest(false);
+    setText("");
+  };
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+    "div",
+    {
+      style: {
+        background: C.panel,
+        border: `1px solid ${C.border}`,
+        borderRadius: 10,
+        padding: 12,
+        marginBottom: 10
+      },
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { fontSize: 12, color: C.dim }, children: [
+          s.namespace,
+          " \xB7 ",
+          s.key
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: { margin: "6px 0 10px", fontSize: 15 }, children: s.value }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { display: "flex", gap: 4 }, children: [
+          [1, 2, 3, 4, 5].map((n) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            "button",
+            {
+              type: "button",
+              "aria-label": `${n} star${n > 1 ? "s" : ""}`,
+              onClick: () => rate(n),
+              style: {
+                background: "transparent",
+                border: "none",
+                cursor: "pointer",
+                fontSize: 20,
+                color: mine && n <= mine ? C.emeraldSoft : C.border
+              },
+              children: "\u2605"
+            },
+            n
+          )),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            "button",
+            {
+              type: "button",
+              onClick: () => setShowSuggest((v) => !v),
+              style: {
+                marginLeft: "auto",
+                background: "transparent",
+                color: C.emeraldSoft,
+                border: `1px solid ${C.border}`,
+                borderRadius: 6,
+                padding: "4px 10px",
+                fontSize: 12,
+                cursor: "pointer"
+              },
+              children: sent ? "Suggested \u2713" : "Suggest"
+            }
+          )
+        ] }),
+        showSuggest && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { marginTop: 10 }, children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            "textarea",
+            {
+              value: text,
+              onChange: (e) => setText(e.target.value),
+              rows: 3,
+              placeholder: "Your suggested translation\u2026",
+              style: {
+                width: "100%",
+                background: C.bg,
+                color: C.text,
+                border: `1px solid ${C.border}`,
+                borderRadius: 6,
+                padding: 8,
+                fontSize: 14,
+                resize: "vertical"
+              }
+            }
+          ),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            "button",
+            {
+              type: "button",
+              onClick: submitSuggestion,
+              style: {
+                marginTop: 6,
+                background: C.emerald,
+                color: "#03110c",
+                border: "none",
+                borderRadius: 6,
+                padding: "8px 12px",
+                fontWeight: 700,
+                cursor: "pointer"
+              },
+              children: "Send suggestion"
+            }
+          )
+        ] })
+      ]
+    }
+  );
+}
+
+// src/react/plugin.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function makeStore() {
+  let open = false;
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    isOpen: () => open,
+    set(v) {
+      if (open !== v) {
+        open = v;
+        listeners.forEach((l) => l());
+      }
+    },
+    subscribe(l) {
+      listeners.add(l);
+      return () => listeners.delete(l);
+    }
+  };
+}
+function feedbackPlugin(options) {
+  const store = makeStore();
+  let client = null;
+  function Outlet() {
+    const isOpen = (0, import_react2.useSyncExternalStore)(
+      store.subscribe,
+      store.isOpen,
+      store.isOpen
+    );
+    if (!isOpen || !client || typeof document === "undefined") return null;
+    const c = client;
+    return (0, import_react_dom.createPortal)(
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+        FeedbackPanel,
+        {
+          client: c,
+          keys: options.keys,
+          onClose: () => {
+            store.set(false);
+            void c.flush();
+          }
+        }
+      ),
+      document.body
+    );
+  }
+  return {
+    name: "@verbumia/feedback",
+    setup(ctx) {
+      client = new FeedbackClient({
+        apiBase: options.apiBase ?? ctx.config.apiBase ?? "https://api.verbumia.ca",
+        projectId: options.projectId ?? ctx.config.projectUuid,
+        language: options.language ?? ctx.config.defaultLocale,
+        endUserId: options.endUserId,
+        fetchImpl: options.fetchImpl
+      });
+      const controller = {
+        open: () => store.set(true),
+        close: () => {
+          store.set(false);
+          void client?.flush();
+        },
+        client
+      };
+      options.onReady?.(controller);
+      if (options.controllerRef) options.controllerRef.current = controller;
+      return () => {
+        if (options.controllerRef) options.controllerRef.current = null;
+        void client?.flush();
+      };
+    },
+    render: () => /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(Outlet, {})
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FeedbackClient,
+  FeedbackError,
+  FeedbackPanel,
+  feedbackPlugin,
+  hasKeyRegistry,
+  resolveKeys
+});
+//# sourceMappingURL=index.cjs.map