@verbumia/feedback 0.1.0

package/dist/core/index.js

@@ -0,0 +1,16 @@
+import "../chunk-5NA2TFPG.js";
+import {
+  FeedbackClient,
+  FeedbackError,
+  SDK_TOS_VERSION,
+  hasKeyRegistry,
+  resolveKeys
+} from "../chunk-OX4RJD5H.js";
+export {
+  FeedbackClient,
+  FeedbackError,
+  SDK_TOS_VERSION,
+  hasKeyRegistry,
+  resolveKeys
+};
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/keys-BySe1O6V.d.ts

@@ -0,0 +1,25 @@
+import { D as DeclaredKey } from './client-CPEcvn23.js';
+
+/**
+ * On-screen key discovery.
+ *
+ * Preferred source: the `@verbumia/*-i18n` SDK exposes a lightweight key
+ * registry of keys it has rendered. When that registry is present on the
+ * global (the i18n SDK publishes `globalThis.__verbumia_key_registry__`),
+ * we read the keys touched on the current view. Otherwise the host app
+ * passes an explicit `keys` list — the always-available fallback.
+ *
+ * The registry contract is intentionally tiny so any framework port of the
+ * i18n SDK can implement it without depending on this package.
+ */
+
+/** True when a compatible `@verbumia/*-i18n` registry is detectable. */
+declare function hasKeyRegistry(): boolean;
+/**
+ * Resolve the on-screen keys: explicit `keys` prop always wins (it is the
+ * customer's authoritative declaration); otherwise fall back to the i18n
+ * registry snapshot; otherwise an empty list (widget shows "no strings").
+ */
+declare function resolveKeys(explicit?: DeclaredKey[]): DeclaredKey[];
+
+export { hasKeyRegistry as h, resolveKeys as r };

package/dist/keys-Dg_nv16u.d.cts

@@ -0,0 +1,25 @@
+import { D as DeclaredKey } from './client-CPEcvn23.cjs';
+
+/**
+ * On-screen key discovery.
+ *
+ * Preferred source: the `@verbumia/*-i18n` SDK exposes a lightweight key
+ * registry of keys it has rendered. When that registry is present on the
+ * global (the i18n SDK publishes `globalThis.__verbumia_key_registry__`),
+ * we read the keys touched on the current view. Otherwise the host app
+ * passes an explicit `keys` list — the always-available fallback.
+ *
+ * The registry contract is intentionally tiny so any framework port of the
+ * i18n SDK can implement it without depending on this package.
+ */
+
+/** True when a compatible `@verbumia/*-i18n` registry is detectable. */
+declare function hasKeyRegistry(): boolean;
+/**
+ * Resolve the on-screen keys: explicit `keys` prop always wins (it is the
+ * customer's authoritative declaration); otherwise fall back to the i18n
+ * registry snapshot; otherwise an empty list (widget shows "no strings").
+ */
+declare function resolveKeys(explicit?: DeclaredKey[]): DeclaredKey[];
+
+export { hasKeyRegistry as h, resolveKeys as r };

package/dist/native/index.cjs

@@ -0,0 +1,575 @@
+"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/native/index.ts
+var native_exports = {};
+__export(native_exports, {
+  FeedbackClient: () => FeedbackClient,
+  FeedbackError: () => FeedbackError,
+  FeedbackModal: () => FeedbackModal,
+  feedbackPlugin: () => feedbackPlugin,
+  hasKeyRegistry: () => hasKeyRegistry,
+  resolveKeys: () => resolveKeys
+});
+module.exports = __toCommonJS(native_exports);
+
+// src/native/plugin.tsx
+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/native/panel.tsx
+var import_react = require("react");
+var import_react_native = require("react-native");
+
+// 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/native/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 FeedbackModal(props) {
+  const { client, visible, 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 (visible && consented) void loadStrings();
+  }, [visible, consented, loadStrings]);
+  const accept = (0, import_react.useCallback)(async () => {
+    setBusy(true);
+    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)(
+    import_react_native.Modal,
+    {
+      visible,
+      transparent: true,
+      animationType: "slide",
+      onRequestClose: onClose,
+      children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_native.View, { style: { flex: 1, backgroundColor: "rgba(0,0,0,.55)", justifyContent: "flex-end" }, children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+        import_react_native.View,
+        {
+          style: {
+            maxHeight: "85%",
+            backgroundColor: C.bg,
+            borderTopWidth: 1,
+            borderColor: C.border,
+            padding: 18
+          },
+          children: [
+            /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+              import_react_native.View,
+              {
+                style: {
+                  flexDirection: "row",
+                  justifyContent: "space-between",
+                  marginBottom: 12
+                },
+                children: [
+                  /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_native.Text, { style: { color: C.emeraldSoft, fontWeight: "700", fontSize: 16 }, children: "Translation feedback" }),
+                  /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_native.TouchableOpacity, { onPress: onClose, accessibilityLabel: "Close", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_native.Text, { style: { color: C.dim, fontSize: 20 }, children: "\xD7" }) })
+                ]
+              }
+            ),
+            error ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_native.Text, { style: { color: "#f87171", marginBottom: 8 }, children: error }) : null,
+            !consented ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_react_native.View, { children: [
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_native.Text, { style: { color: C.text, lineHeight: 21 }, 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)(
+                import_react_native.TouchableOpacity,
+                {
+                  disabled: busy,
+                  onPress: accept,
+                  style: {
+                    marginTop: 14,
+                    backgroundColor: C.emerald,
+                    borderRadius: 8,
+                    padding: 14
+                  },
+                  children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_native.Text, { style: { color: "#03110c", fontWeight: "700", textAlign: "center" }, children: busy ? "\u2026" : `I accept the terms (v${client.tosVersion})` })
+                }
+              )
+            ] }) : /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_native.ScrollView, { children: !strings.length ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_native.Text, { style: { color: C.dim }, children: busy ? "Loading\u2026" : "No strings to review on this view." }) : strings.map((s) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+              StringRow,
+              {
+                s,
+                client
+              },
+              `${s.namespace}:${s.key}`
+            )) })
+          ]
+        }
+      ) })
+    }
+  );
+}
+function StringRow(props) {
+  const { s, client } = props;
+  const [mine, setMine] = (0, import_react.useState)(s.my_rating);
+  const [show, setShow] = (0, import_react.useState)(false);
+  const [text, setText] = (0, import_react.useState)("");
+  const [sent, setSent] = (0, import_react.useState)(false);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+    import_react_native.View,
+    {
+      style: {
+        backgroundColor: C.panel,
+        borderWidth: 1,
+        borderColor: C.border,
+        borderRadius: 10,
+        padding: 12,
+        marginBottom: 10
+      },
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_react_native.Text, { style: { color: C.dim, fontSize: 12 }, children: [
+          s.namespace,
+          " \xB7 ",
+          s.key
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_native.Text, { style: { color: C.text, fontSize: 15, marginVertical: 6 }, children: s.value }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_react_native.View, { style: { flexDirection: "row" }, children: [
+          [1, 2, 3, 4, 5].map((n) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            import_react_native.TouchableOpacity,
+            {
+              accessibilityLabel: `${n} stars`,
+              onPress: () => {
+                setMine(n);
+                client.rate({
+                  namespace: s.namespace,
+                  key: s.key,
+                  language: client.language,
+                  translation_hash: s.translation_hash,
+                  stars: n
+                });
+              },
+              children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+                import_react_native.Text,
+                {
+                  style: {
+                    fontSize: 22,
+                    marginRight: 4,
+                    color: mine && n <= mine ? C.emeraldSoft : C.border
+                  },
+                  children: "\u2605"
+                }
+              )
+            },
+            n
+          )),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            import_react_native.TouchableOpacity,
+            {
+              onPress: () => setShow(!show),
+              style: { marginLeft: "auto" },
+              children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_native.Text, { style: { color: C.emeraldSoft }, children: sent ? "Suggested \u2713" : "Suggest" })
+            }
+          )
+        ] }),
+        show ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_react_native.View, { style: { marginTop: 10 }, children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            import_react_native.TextInput,
+            {
+              value: text,
+              onChangeText: setText,
+              multiline: true,
+              numberOfLines: 3,
+              placeholder: "Your suggested translation\u2026",
+              placeholderTextColor: C.dim,
+              style: {
+                backgroundColor: C.bg,
+                color: C.text,
+                borderWidth: 1,
+                borderColor: C.border,
+                borderRadius: 6,
+                padding: 8
+              }
+            }
+          ),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            import_react_native.TouchableOpacity,
+            {
+              onPress: () => {
+                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);
+                setShow(false);
+                setText("");
+              },
+              style: {
+                marginTop: 6,
+                backgroundColor: C.emerald,
+                borderRadius: 6,
+                padding: 10
+              },
+              children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_native.Text, { style: { color: "#03110c", fontWeight: "700", textAlign: "center" }, children: "Send suggestion" })
+            }
+          )
+        ] }) : null
+      ]
+    }
+  );
+}
+
+// src/native/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 (!client) return null;
+    const c = client;
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+      FeedbackModal,
+      {
+        client: c,
+        visible: isOpen,
+        keys: options.keys,
+        onClose: () => {
+          store.set(false);
+          void c.flush();
+        }
+      }
+    );
+  }
+  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,
+  FeedbackModal,
+  feedbackPlugin,
+  hasKeyRegistry,
+  resolveKeys
+});
+//# sourceMappingURL=index.cjs.map