@verbumia/feedback 0.1.0

package/CONTRACT.md

@@ -0,0 +1,165 @@
+# `@verbumia/feedback` — wire contract (v4 — task 616: tosVersion = SDK build-time constant)
+
+Canonical reference for what the widget SDK sends and what the Verbumia
+backend accepts. Entry points `/react`, `/native`, `/vue`, `/svelte`,
+`/core` are interface-only differences; the WIRE shape (§1–§5) is
+identical for all. Backend source-of-truth: `docs/feedback-api-contract.md`.
+Supersedes the v3 artifact `b6324d39` (v2 `c8e86de1`, v1 `e614b48b`).
+
+**v4 change (task 616):** `tosVersion` is NO LONGER an integrator config
+field. It is a BUILD-TIME constant baked into the package
+(`SDK_TOS_VERSION`, exported from `@verbumia/feedback/core`), sent
+automatically on `POST /v1/feedback/tos`. Rationale: a stale (e.g.
+native) app must record consent to the ToS version IT shipped, not
+backend-latest. A ToS-TEXT change ⇒ bump `SDK_TOS_VERSION` + cut a new
+SDK release (+ add the version to the backend acceptable set). The wire
+body still carries `tos_version` (now SDK-sourced); the backend accepts
+any KNOWN version, records it as-sent, and 422s `tos_version_unknown`
+for unrecognized ones. No config field across ANY entry takes
+`tosVersion`. Wire shape otherwise byte-identical to v3.
+
+## 0b. Vue / Svelte entries (task 611 — adapters over /core)
+
+`@verbumia/feedback/vue` and `@verbumia/feedback/svelte` are idiomatic
+standalone adapters over the FROZEN `/core` `FeedbackClient` (the
+host-i18n plugin-slot half is descoped — no `@verbumia/vue-i18n` /
+`@verbumia/svelte-i18n` source). Same principles as the React plugin:
+isolated open-state (never re-renders the host app), imperative
+controller, server-minted sessionId (no client `groupingKey`).
+
+- **/vue**: `createFeedback(config): { client, isOpen: Ref<boolean>,
+  controller: { open, close, client }, FeedbackPanel }`. `FeedbackPanel`
+  is a functional component (Teleport-to-body); mount once near root.
+  `config = { apiBase, projectId, language, endUserId?, keys?, fetchImpl? }` (NO tosVersion — build-time constant) (explicit — no i18n provider to inherit from).
+- **/svelte**: `createFeedback(config): { client, isOpen:
+  Writable<boolean>, strings: Writable<FeedbackString[]>, open(),
+  close(), loadStrings(), rate(), suggest() }`. HEADLESS (idiomatic
+  Svelte stores; consumer renders its own panel). Same `config` shape.
+
+`vue` / `svelte` are OPTIONAL peer deps (only the respective entry needs
+them). The wire contract (§1–§5) is byte-identical to v2.
+
+## 0. Integration architecture (task 599)
+
+`@verbumia/feedback` is a **plugin of the `@verbumia/*-i18n`
+provider** — NOT a separate React context/provider. The customer adds
+`feedbackPlugin({ … })` to the i18n provider's `plugins`
+slot. The provider calls the plugin's `setup({ i18n, config })` once
+(the plugin reuses the provider's `apiBase` / `projectUuid` /
+`defaultLocale` — no re-config) and mounts the plugin's `render()` as an
+**isolated sibling leaf**. The panel's open/close lives in a private
+store the outlet subscribes to, so enabling/opening feedback **never
+re-renders the host app**. The host triggers the panel via its own CTA
+through the imperative controller (`{ open, close }`) delivered via
+`onReady` / `controllerRef`. No second provider is mounted.
+
+Base URL: `FeedbackConfig.apiBase` (e.g. `https://api.verbumia.ca`),
+trailing slashes trimmed. All bodies are `application/json`. Errors are
+RFC 7807 problem+json with a stable `code`.
+
+## 1. ToS acceptance → token bootstrap
+
+```
+POST <apiBase>/v1/feedback/tos
+{
+  "project_id":   "<project uuid>",
+  "end_user_id":  "<opaque id | null>",
+  "tos_version":  "2026-05-18",
+  "locale":       "fr | null"
+}
+```
+
+**sessionId / grouping_key is MINTED SERVER-SIDE (task 599).** The
+client MUST NOT send or self-generate it — there is no
+`grouping_key` request field and no `groupingKey` SDK config option.
+The backend generates it (server-known + validated), returns it as
+`grouping_key`, and binds it into the JWT. The SDK exposes it read-only
+via `client.sessionId` after `acceptTos()`. A returning `end_user_id`
+keeps its stable server value; a new end user gets a fresh
+`sess_<uuid7>`.
+
+`200` → `TokenBundle`:
+
+```
+{ "access_token","token_type":"Bearer","expires_in",
+  "refresh_token","refresh_expires_in",
+  "end_user_id","tos_version","grouping_key" }
+```
+
+`403 end_user_eval_disabled` — add-on not on the project's plan.
+`422 tos_version_unknown` — body carries `current_tos_version` + `acceptable_tos_versions` (SDK sends its build-time SDK_TOS_VERSION; integrator never sets it).
+Not gated by a token (this call bootstraps one).
+
+## 2. Token refresh (rotating)
+
+```
+POST <apiBase>/v1/feedback/token/refresh
+{ "refresh_token": "<opaque>" }
+```
+
+`200` → a fresh `TokenBundle` (refresh token is rotated; the old one is
+invalidated). `401 feedback_refresh_invalid` → restart at §1.
+
+## 3. Strings on the current view  (Bearer)
+
+```
+GET <apiBase>/v1/feedback/strings?language=<bcp47>
+    [&keys=ns:key,ns:key][&namespace=<slug>][&limit=200]
+Authorization: Bearer <access_token>
+```
+
+`200`:
+
+```
+{ "project_id","language",
+  "strings":[ { "namespace","key","key_uuid","language_uuid",
+                "value","translation_hash",
+                "avg_stars": number|null,"ratings_count","my_rating": int|null } ] }
+```
+
+`translation_hash` is the rating target; echo it back unchanged in §4/§5.
+
+## 4. Ratings  (Bearer, batched)
+
+```
+POST <apiBase>/v1/feedback/ratings
+Authorization: Bearer <access_token>
+{ "ratings":[ { "namespace","key","language","translation_hash","stars":1..5 } ] }
+```
+
+1..50 items. Idempotent per (end user, key, language, hash) — last write
+wins. `200` → `{ "accepted","rejected","items":[…] }`.
+
+## 5. Suggestions  (Bearer, batched)
+
+```
+POST <apiBase>/v1/feedback/suggestions
+Authorization: Bearer <access_token>
+{ "suggestions":[ { "namespace","key","language","translation_hash",
+                     "suggested_text":"1..2000","comment":"<=500 | null" } ] }
+```
+
+1..20 items. Created `status=pending`; nothing auto-publishes (customer
+moderates). `200` → `{ "accepted","rejected","items":[ { "suggestion_id",… } ] }`.
+
+## 6. Transport rules (ltm 280, mirrors the missing-handler)
+
+- Ratings + suggestions are **queued**, then flushed on a debounce
+  (`flushDebounceMs`, default 1500 ms) or when the queue reaches
+  `maxBatch` (default 20), or on widget close.
+- **Best-effort**: a transport or auth failure re-queues the batch once
+  and is swallowed — the SDK never throws into the host render path.
+- On `401` the client performs **one** transparent
+  `/token/refresh` then retries the request; a failed refresh clears
+  consent and the widget returns to the §1 step.
+- Outgoing batch posts carry `X-SDK: @verbumia/feedback@<ver>`.
+
+## 7. Auth isolation
+
+The end-user token is cryptographically separate from Verbumia customer
+auth (distinct signing key + `iss`/`aud`); it only authorises
+`/v1/feedback/*`. It is never sent to any other endpoint.
+
+---
+Frozen 2026-05-18. Changes require a contract bump + notifying master and
+client-admin.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Verbumia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# @verbumia/feedback
+
+Embed a Verbumia **End-User Translation Evaluation** widget in your app.
+Your end users accept a short ToS, then rate (5-star) and suggest
+alternatives for the translations on screen. You moderate everything from
+the Verbumia dashboard — nothing auto-publishes.
+
+- `@verbumia/feedback/react` — React (web)
+- `@verbumia/feedback/native` — React Native / Expo
+- `@verbumia/feedback/core` — framework-agnostic client (advanced)
+
+MIT. Add-on available from the **Pro** plan upward.
+
+## Install
+
+```sh
+npm i @verbumia/feedback
+```
+
+`react` (and `react-native` for the native entry) are peer deps.
+
+## Architecture
+
+`@verbumia/feedback` is a **plugin of your existing `@verbumia/*-i18n`
+provider** — not a second context/provider. You add it to the i18n
+provider's `plugins` slot; it reuses that provider's `apiBase` /
+`projectUuid` / locale (no re-config) and never re-renders your app when
+the panel opens. The sessionId is minted server-side — you don't supply
+a cohort/session id.
+
+## React
+
+```tsx
+import { VerbumiaProvider } from "@verbumia/react-i18next";
+import { feedbackPlugin } from "@verbumia/feedback/react";
+
+const feedbackCtl = { current: null };
+
+<VerbumiaProvider
+  token="vrb_live_…"
+  projectUuid="<project-uuid>"
+  defaultLocale="fr"
+  plugins={[
+    feedbackPlugin({
+      tosVersion: "2026-05-18",
+      keys: [{ namespace: "common", key: "home.title" }], // or omit → i18n registry
+      controllerRef: feedbackCtl,                          // imperative handle
+    }),
+  ]}
+>
+  <App />
+</VerbumiaProvider>;
+
+// trigger from your own CTA — no hook, no extra provider:
+<button onClick={() => feedbackCtl.current?.open()}>Rate translations</button>;
+```
+
+`feedbackPlugin` also accepts `onReady(controller)`, and optional
+`apiBase` / `projectId` / `language` overrides (defaults come from the
+i18n provider config).
+
+## React Native / Expo
+
+```tsx
+import { feedbackPlugin } from "@verbumia/feedback/native";
+// same plugin API; renders a bottom-sheet <Modal> instead of a side panel.
+// add it to your @verbumia/react-i18next provider's `plugins` slot.
+```
+
+## Key discovery
+
+If `@verbumia/*-i18n` is on the page it exposes a tiny key registry; the
+widget reads the on-screen keys from it automatically. The explicit
+`keys` prop always overrides it and is the reliable fallback.
+
+## Behaviour
+
+Ratings/suggestions are debounced + batched and sent best-effort — the
+widget never blocks or breaks your app. See [CONTRACT.md](./CONTRACT.md)
+for the exact wire shape.

package/dist/chunk-5NA2TFPG.js

@@ -0,0 +1 @@
+//# sourceMappingURL=chunk-5NA2TFPG.js.map

package/dist/chunk-5NA2TFPG.js.map

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

package/dist/chunk-OX4RJD5H.js

@@ -0,0 +1,242 @@
+// 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/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;
+}
+
+export {
+  FeedbackError,
+  SDK_TOS_VERSION,
+  FeedbackClient,
+  hasKeyRegistry,
+  resolveKeys
+};
+//# sourceMappingURL=chunk-OX4RJD5H.js.map

package/dist/chunk-OX4RJD5H.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/types.ts","../src/core/tos.ts","../src/core/client.ts","../src/core/keys.ts"],"sourcesContent":["/**\n * Wire types for the Verbumia End-User Translation Evaluation API.\n * Canonical reference: ./CONTRACT.md (frozen). Backend task 591.\n */\n\nexport interface FeedbackConfig {\n  /** API base, no trailing slash needed. e.g. https://api.verbumia.ca */\n  apiBase: string;\n  /** Public project UUID the widget targets. */\n  projectId: string;\n  /**\n   * sessionId / grouping_key is MINTED SERVER-SIDE by the Verbumia\n   * backend at POST /v1/feedback/tos and returned in the token bundle\n   * (`TokenBundle.grouping_key`). The widget receives + sends it; it\n   * MUST NOT self-generate it. There is intentionally no client config\n   * field for it.\n   */\n  /**\n   * NOTE: there is intentionally NO `tosVersion` field. The ToS version\n   * is a BUILD-TIME constant baked into @verbumia/feedback at release\n   * (`SDK_TOS_VERSION`, task 616) — integrators do not set it; the SDK\n   * sends it automatically.\n   */\n  /** Optional opaque end-user id; server generates one when absent. */\n  endUserId?: string;\n  /** BCP-47 language the widget rates strings in (e.g. \"fr\"). */\n  language: string;\n  /** Optional locale tag stored for analytics. */\n  locale?: string;\n  /** Debounce window (ms) before a queued batch is flushed. Default 1500. */\n  flushDebounceMs?: number;\n  /** Max queued items before an immediate flush. Default 20. */\n  maxBatch?: number;\n  /** Injected fetch (tests / RN polyfills). Defaults to global fetch. */\n  fetchImpl?: typeof fetch;\n}\n\nexport interface TokenBundle {\n  access_token: string;\n  token_type: \"Bearer\";\n  expires_in: number;\n  refresh_token: string;\n  refresh_expires_in: number;\n  end_user_id: string;\n  tos_version: string;\n  grouping_key: string;\n}\n\nexport interface FeedbackString {\n  namespace: string;\n  key: string;\n  key_uuid: string;\n  language_uuid: string;\n  value: string;\n  translation_hash: string;\n  avg_stars: number | null;\n  ratings_count: number;\n  my_rating: number | null;\n}\n\nexport interface StringsResponse {\n  project_id: string;\n  language: string;\n  strings: FeedbackString[];\n}\n\n/** A 5-star rating queued for a rendered string variant. */\nexport interface RatingInput {\n  namespace: string;\n  key: string;\n  language: string;\n  translation_hash: string;\n  stars: number; // 1..5\n}\n\n/** A suggested alternative translation queued for moderation. */\nexport interface SuggestionInput {\n  namespace: string;\n  key: string;\n  language: string;\n  translation_hash: string;\n  suggested_text: string;\n  comment?: string;\n}\n\nexport interface BatchResponse {\n  accepted: number;\n  rejected: number;\n  items: Array<Record<string, unknown>>;\n}\n\n/** A key the host app declares as on-screen. */\nexport interface DeclaredKey {\n  namespace: string;\n  key: string;\n}\n\nexport class FeedbackError extends Error {\n  constructor(\n    message: string,\n    readonly status?: number,\n    readonly code?: string,\n  ) {\n    super(message);\n    this.name = \"FeedbackError\";\n  }\n}\n","/**\n * BUILD-TIME ToS version constant (task 616, human decision option B).\n *\n * This is baked into the @verbumia/feedback PACKAGE at release. It is\n * NOT an integrator-set config field and NOT server-driven: a stale\n * (e.g. native) app must record consent to the ToS version IT shipped\n * and displayed, for legal correctness — never backend-latest.\n *\n * Releasing a ToS-TEXT change ⇒ bump this constant + cut a new\n * @verbumia/feedback release (per the human/real-CI publish handoff).\n * The backend accepts any version in its acceptable set and records it.\n */\nexport const SDK_TOS_VERSION = \"2026-05-18\";\n","/**\n * Framework-agnostic Verbumia feedback client.\n *\n * Responsibilities:\n *  - versioned-ToS acceptance -> scoped end-user JWT bootstrap\n *  - transparent access-token refresh (rotating refresh token)\n *  - fetch on-screen strings for the widget\n *  - debounced + size-capped batched POST of ratings / suggestions,\n *    mirroring the missing-handler transport contract (ltm 280):\n *    best-effort, never throws into the host app render path.\n *\n * The React and React Native entry points are thin UI shells over this.\n */\n\nimport {\n  type BatchResponse,\n  type FeedbackConfig,\n  FeedbackError,\n  type RatingInput,\n  type StringsResponse,\n  type SuggestionInput,\n  type TokenBundle,\n} from \"./types\";\nimport { SDK_TOS_VERSION } from \"./tos\";\n\nconst SDK_LIB = \"@verbumia/feedback\";\nconst SDK_VER = \"0.1.0\";\n\ntype QueueItem =\n  | { kind: \"rating\"; payload: RatingInput }\n  | { kind: \"suggestion\"; payload: SuggestionInput };\n\nexport class FeedbackClient {\n  private cfg: Required<\n    Pick<FeedbackConfig, \"flushDebounceMs\" | \"maxBatch\">\n  > &\n    FeedbackConfig;\n  private fetchImpl: typeof fetch;\n  private tokens: TokenBundle | null = null;\n  private queue: QueueItem[] = [];\n  private timer: ReturnType<typeof setTimeout> | null = null;\n  private bootstrapping: Promise<TokenBundle> | null = null;\n\n  constructor(config: FeedbackConfig) {\n    this.cfg = {\n      flushDebounceMs: 1500,\n      maxBatch: 20,\n      ...config,\n    };\n    const f = config.fetchImpl ?? globalThis.fetch;\n    if (!f) {\n      throw new FeedbackError(\n        \"no fetch implementation available; pass config.fetchImpl\",\n      );\n    }\n    this.fetchImpl = f.bind(globalThis);\n  }\n\n  private base(): string {\n    return this.cfg.apiBase.replace(/\\/+$/, \"\");\n  }\n\n  get endUserId(): string | undefined {\n    return this.tokens?.end_user_id ?? this.cfg.endUserId;\n  }\n\n  get hasConsented(): boolean {\n    return this.tokens !== null;\n  }\n\n  /** Server-minted sessionId / grouping_key (from the token bundle).\n   * Available only after `acceptTos()`; never client-generated. */\n  get sessionId(): string | undefined {\n    return this.tokens?.grouping_key;\n  }\n\n  /** BCP-47 language the widget is rating strings in. */\n  get language(): string {\n    return this.cfg.language;\n  }\n\n  /** ToS version the end user is asked to accept — the SDK's\n   * build-time constant (task 616). NOT integrator/server set. */\n  get tosVersion(): string {\n    return SDK_TOS_VERSION;\n  }\n\n  /**\n   * Accept the ToS and bootstrap a scoped token. Idempotent: a second call\n   * returns the in-flight / existing bundle rather than re-accepting.\n   */\n  async acceptTos(): Promise<TokenBundle> {\n    if (this.tokens) return this.tokens;\n    if (this.bootstrapping) return this.bootstrapping;\n    this.bootstrapping = (async () => {\n      const res = await this.fetchImpl(`${this.base()}/v1/feedback/tos`, {\n        method: \"POST\",\n        headers: { \"Content-Type\": \"application/json\" },\n        body: JSON.stringify({\n          // NO grouping_key: server-minted (task 599). It comes back in\n          // the token bundle and is bound into the JWT server-side.\n          project_id: this.cfg.projectId,\n          end_user_id: this.cfg.endUserId,\n          tos_version: SDK_TOS_VERSION,\n          locale: this.cfg.locale,\n        }),\n      });\n      if (!res.ok) throw await this.problem(res, \"tos acceptance failed\");\n      this.tokens = (await res.json()) as TokenBundle;\n      return this.tokens;\n    })();\n    try {\n      return await this.bootstrapping;\n    } finally {\n      this.bootstrapping = null;\n    }\n  }\n\n  private async refresh(): Promise<void> {\n    if (!this.tokens) throw new FeedbackError(\"not consented\");\n    const res = await this.fetchImpl(\n      `${this.base()}/v1/feedback/token/refresh`,\n      {\n        method: \"POST\",\n        headers: { \"Content-Type\": \"application/json\" },\n        body: JSON.stringify({ refresh_token: this.tokens.refresh_token }),\n      },\n    );\n    if (!res.ok) {\n      this.tokens = null; // force a fresh ToS step\n      throw await this.problem(res, \"token refresh failed\");\n    }\n    this.tokens = (await res.json()) as TokenBundle;\n  }\n\n  /** Authenticated fetch with a single transparent refresh-on-401 retry. */\n  private async authed(\n    path: string,\n    init: RequestInit,\n    retry = true,\n  ): Promise<Response> {\n    if (!this.tokens) await this.acceptTos();\n    const res = await this.fetchImpl(`${this.base()}${path}`, {\n      ...init,\n      headers: {\n        ...(init.headers ?? {}),\n        Authorization: `Bearer ${this.tokens!.access_token}`,\n      },\n    });\n    if (res.status === 401 && retry) {\n      await this.refresh();\n      return this.authed(path, init, false);\n    }\n    return res;\n  }\n\n  /** Strings rendered on the current view, with this end user's prior rating. */\n  async getStrings(opts?: {\n    keys?: Array<{ namespace: string; key: string }>;\n    namespace?: string;\n    limit?: number;\n  }): Promise<StringsResponse> {\n    const qs = new URLSearchParams({ language: this.cfg.language });\n    if (opts?.keys?.length) {\n      qs.set(\"keys\", opts.keys.map((k) => `${k.namespace}:${k.key}`).join(\",\"));\n    }\n    if (opts?.namespace) qs.set(\"namespace\", opts.namespace);\n    if (opts?.limit) qs.set(\"limit\", String(opts.limit));\n    const res = await this.authed(`/v1/feedback/strings?${qs}`, {\n      method: \"GET\",\n    });\n    if (!res.ok) throw await this.problem(res, \"failed to load strings\");\n    return (await res.json()) as StringsResponse;\n  }\n\n  /** Queue a rating; flushed on debounce or when the batch fills. */\n  rate(payload: RatingInput): void {\n    this.enqueue({ kind: \"rating\", payload });\n  }\n\n  /** Queue a suggestion; flushed on debounce or when the batch fills. */\n  suggest(payload: SuggestionInput): void {\n    this.enqueue({ kind: \"suggestion\", payload });\n  }\n\n  private enqueue(item: QueueItem): void {\n    this.queue.push(item);\n    if (this.queue.length >= this.cfg.maxBatch) {\n      void this.flush();\n      return;\n    }\n    if (this.timer) clearTimeout(this.timer);\n    this.timer = setTimeout(() => void this.flush(), this.cfg.flushDebounceMs);\n  }\n\n  /**\n   * Flush queued items. Best-effort: a transport/auth failure re-queues the\n   * batch once and swallows the error so the host app never sees a throw.\n   */\n  async flush(): Promise<void> {\n    if (this.timer) {\n      clearTimeout(this.timer);\n      this.timer = null;\n    }\n    if (!this.queue.length) return;\n    const batch = this.queue;\n    this.queue = [];\n    const ratings = batch\n      .filter((b) => b.kind === \"rating\")\n      .map((b) => b.payload as RatingInput);\n    const suggestions = batch\n      .filter((b) => b.kind === \"suggestion\")\n      .map((b) => b.payload as SuggestionInput);\n    try {\n      if (ratings.length) {\n        await this.postBatch(\"/v1/feedback/ratings\", { ratings });\n      }\n      if (suggestions.length) {\n        await this.postBatch(\"/v1/feedback/suggestions\", { suggestions });\n      }\n    } catch {\n      // Re-queue once; feedback must never break the host app.\n      this.queue.unshift(...batch);\n    }\n  }\n\n  private async postBatch(\n    path: string,\n    body: unknown,\n  ): Promise<BatchResponse> {\n    const res = await this.authed(path, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\", \"X-SDK\": `${SDK_LIB}@${SDK_VER}` },\n      body: JSON.stringify(body),\n    });\n    if (!res.ok) throw await this.problem(res, \"batch post failed\");\n    return (await res.json()) as BatchResponse;\n  }\n\n  private async problem(res: Response, fallback: string): Promise<FeedbackError> {\n    let code: string | undefined;\n    let detail = fallback;\n    try {\n      const body = (await res.json()) as { code?: string; detail?: string };\n      code = body.code;\n      if (body.detail) detail = body.detail;\n    } catch {\n      /* non-JSON body */\n    }\n    return new FeedbackError(detail, res.status, code);\n  }\n}\n","/**\n * On-screen key discovery.\n *\n * Preferred source: the `@verbumia/*-i18n` SDK exposes a lightweight key\n * registry of keys it has rendered. When that registry is present on the\n * global (the i18n SDK publishes `globalThis.__verbumia_key_registry__`),\n * we read the keys touched on the current view. Otherwise the host app\n * passes an explicit `keys` list — the always-available fallback.\n *\n * The registry contract is intentionally tiny so any framework port of the\n * i18n SDK can implement it without depending on this package.\n */\n\nimport type { DeclaredKey } from \"./types\";\n\nconst REGISTRY_GLOBAL = \"__verbumia_key_registry__\";\n\ninterface KeyRegistry {\n  /** Returns the keys rendered since the last `reset()` (or ever). */\n  snapshot(): DeclaredKey[];\n  reset?(): void;\n}\n\nfunction getRegistry(): KeyRegistry | null {\n  const g = globalThis as Record<string, unknown>;\n  const reg = g[REGISTRY_GLOBAL];\n  if (\n    reg &&\n    typeof (reg as KeyRegistry).snapshot === \"function\"\n  ) {\n    return reg as KeyRegistry;\n  }\n  return null;\n}\n\n/** True when a compatible `@verbumia/*-i18n` registry is detectable. */\nexport function hasKeyRegistry(): boolean {\n  return getRegistry() !== null;\n}\n\n/**\n * Resolve the on-screen keys: explicit `keys` prop always wins (it is the\n * customer's authoritative declaration); otherwise fall back to the i18n\n * registry snapshot; otherwise an empty list (widget shows \"no strings\").\n */\nexport function resolveKeys(explicit?: DeclaredKey[]): DeclaredKey[] {\n  if (explicit && explicit.length) return dedupe(explicit);\n  const reg = getRegistry();\n  if (reg) return dedupe(reg.snapshot());\n  return [];\n}\n\nfunction dedupe(keys: DeclaredKey[]): DeclaredKey[] {\n  const seen = new Set<string>();\n  const out: DeclaredKey[] = [];\n  for (const k of keys) {\n    const id = `${k.namespace}:${k.key}`;\n    if (!seen.has(id)) {\n      seen.add(id);\n      out.push(k);\n    }\n  }\n  return out;\n}\n"],"mappings":"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","names":[]}