@verbumia/react-i18next 0.8.0 → 0.9.1

package/README.md

@@ -66,6 +66,10 @@ interface VerbumiaConfig {
   defaultNS?: string;             // alias: default namespace for single-ns apps
   apiBase?: string;               // default 'https://api.verbumia.dev'
   cdnBase?: string;               // default 'https://cdn.verbumia.ca'
+  version?: string;               // version slug, default 'main' (in cache keys)
+  versionSlug?: string;           // @deprecated alias of `version`
+  env?: 'prod' | 'dev';           // default 'prod' (drives fetch source)
+  plugins?: VerbumiaPlugin[];     // e.g. @verbumia/feedback, @verbumia/realtime
   transport?: (batch: MissingKeyEvent[]) => void | Promise<void>;
   missingHandler?: 'send' | 'log' | 'off';   // default 'send'
   flushIntervalMs?: number;       // default 5000
@@ -74,6 +78,19 @@ interface VerbumiaConfig {
 }
 ```
 
+`version` selects which published version's bundles to load
+(`/p/<project>/<version>/latest/...`); it defaults to `'main'` and is part
+of the SDK's bundle cache keys, so two providers with different `version`
+values never share cached bundles. `versionSlug` is a **deprecated** alias
+of `version` (if both are set, `version` wins).
+
+> **Removed in 0.9.0:** the `liveUpdates` / `centrifugoWsUrl` /
+> `centrifugoTokenEndpoint` config keys. Realtime updates now live in the
+> separate [`@verbumia/realtime`](../realtime) plugin (see
+> [Realtime updates](#realtime-updates)). Passing any of those keys throws
+> a clear migration error.
+```
+
 ### `useTranslation(defaultNamespace?)`
 
 Returns `{ t, i18n }`.
@@ -95,9 +112,24 @@ interface I18nInstance {
   t: TranslationFunction;                       // for out-of-React use via getI18n()
   missingEvents: MissingKeyEvent[];             // newest first, capped buffer
   flushMissing(): Promise<void>;                // force-flush the pending batch
+  reload(opts?: { locale?: string; namespace?: string }): Promise<void>;
 }
 ```
 
+### `i18n.reload(opts?)`
+
+Bust-refetches already-loaded bundles (bypassing the browser HTTP cache)
+and re-renders. Without `opts` it refreshes every loaded `(locale, ns)`
+bundle; pass `{ locale }` and/or `{ namespace }` to narrow. Returns once
+all refetches settle. Useful for a manual "refresh translations" button,
+and it's what [`@verbumia/realtime`](#realtime-updates) calls on a
+`translations_published` push.
+
+```ts
+await getI18n().reload();                                  // refresh all
+await getI18n().reload({ locale: "fr", namespace: "common" });
+```
+
 ### `<Trans>`
 
 Inline translation with JSX slots:
@@ -168,11 +200,16 @@ interface MissingKeyEvent {
   key: string;
   namespace: string;
   language_code: string;
-  source_value?: string;
+  source_value?: string;               // explicit defaultValue or fallback value; omitted when none (never the key name)
   sdk_meta?: Record<string, unknown>;  // SDK adds {lib, ver, url} automatically
 }
 ```
 
+`source_value` carries the canonical default the SDK has — the `defaultValue`
+you pass to `t()` (object or positional form), or the fallback-language bundle
+value. When there is no default, it is **omitted** (the key name is in `key`),
+so the backend never mistakes a key for a translation.
+
 ### Why the gate matters
 
 Without the gate, every `t("…")` call between mount and bundle resolution
@@ -212,6 +249,38 @@ import { defaultTransport, logTransport } from "@verbumia/react-i18next";
 
 ---
 
+## Realtime updates
+
+Zero-deploy translation updates (subscribe to the project's Centrifugo
+`translations:` channel and bust-refetch on publish) live in the separate
+[`@verbumia/realtime`](../realtime) package — added as a **plugin** of this
+provider, not configured here:
+
+```tsx
+import { VerbumiaProvider } from "@verbumia/react-i18next";
+import { verbumiaRealtime } from "@verbumia/realtime/react";
+
+<VerbumiaProvider
+  {...config}
+  env="dev"
+  plugins={[
+    verbumiaRealtime({ wsUrl: "wss://centrifugo.verbumia.ca/connection/websocket" }),
+  ]}
+>
+  <App />
+</VerbumiaProvider>;
+```
+
+Under the hood the plugin calls [`i18n.reload(...)`](#i18nreloadopts) on
+each `translations_published` push. Realtime is a dev-version-only feature
+(it only subscribes when `env: "dev"`).
+
+> The `liveUpdates` / `centrifugoWsUrl` / `centrifugoTokenEndpoint` config
+> keys were **removed in 0.9.0**. Install `@verbumia/realtime` and use the
+> plugin instead.
+
+---
+
 ## Recipes
 
 ### Next.js (App Router)

package/dist/index.cjs

@@ -35,7 +35,7 @@ var import_react = require("react");
 
 // src/transport.ts
 var SDK_LIB = "@verbumia/react-i18next";
-var SDK_VER = "0.5.2";
+var SDK_VER = true ? "0.9.1" : "0.0.0-dev";
 function defaultTransport(opts) {
   return async (batch) => {
     if (!batch.length) return;
@@ -45,7 +45,9 @@ function defaultTransport(opts) {
         key: e.key,
         namespace: e.namespace,
         language_code: e.language_code,
-        source_value: e.source_value,
+        // Option A (#746): only send source_value when there's a real value;
+        // omit it otherwise (never the key name). Absent = "no default".
+        ...e.source_value !== void 0 ? { source_value: e.source_value } : {},
         sdk_meta: {
           lib: SDK_LIB,
           ver: SDK_VER,
@@ -75,111 +77,6 @@ var logTransport = (batch) => {
   }
 };
 
-// src/live.ts
-var LiveClient = class {
-  constructor(cfg) {
-    this.cfg = cfg;
-  }
-  cfg;
-  _ws = null;
-  _id = 0;
-  _backoffMs = 1e3;
-  _disposed = false;
-  _connectAcked = false;
-  /** Open the socket and try to subscribe. Idempotent — calling twice is a no-op. */
-  async connect() {
-    if (this._ws) return;
-    if (this._disposed) return;
-    this.cfg.onStatus?.("connecting");
-    const token = this.cfg.refreshToken ? await this.cfg.refreshToken() : this.cfg.token;
-    let url = this.cfg.url;
-    if (!url.includes("/connection/websocket")) {
-      url = url.replace(/\/+$/, "") + "/connection/websocket";
-    }
-    const ws = new WebSocket(url);
-    this._ws = ws;
-    this._connectAcked = false;
-    ws.onopen = () => {
-      this._send({ id: ++this._id, connect: { token } });
-    };
-    ws.onmessage = (evt) => this._onFrame(evt.data);
-    ws.onclose = () => this._onClose();
-    ws.onerror = () => {
-    };
-  }
-  dispose() {
-    this._disposed = true;
-    if (this._ws) {
-      try {
-        this._ws.close();
-      } catch {
-      }
-      this._ws = null;
-    }
-    this.cfg.onStatus?.("disconnected");
-  }
-  // ---- internals ----
-  _send(msg) {
-    if (!this._ws || this._ws.readyState !== WebSocket.OPEN) return;
-    try {
-      this._ws.send(JSON.stringify(msg));
-    } catch {
-    }
-  }
-  _onFrame(raw) {
-    let parsed;
-    try {
-      parsed = JSON.parse(raw);
-    } catch {
-      return;
-    }
-    if (!parsed || typeof parsed !== "object") return;
-    if (Object.keys(parsed).length === 0) {
-      this._send({});
-      return;
-    }
-    if (parsed.connect && !this._connectAcked) {
-      this._connectAcked = true;
-      this.cfg.onStatus?.("connected");
-      this._backoffMs = 1e3;
-      this._send({
-        id: ++this._id,
-        subscribe: { channel: this.cfg.channel }
-      });
-      return;
-    }
-    const push = parsed.push;
-    if (push && push.channel === this.cfg.channel && push.pub) {
-      this.cfg.onMessage(push.pub.data);
-    }
-  }
-  _onClose() {
-    this._ws = null;
-    this._connectAcked = false;
-    this.cfg.onStatus?.("disconnected");
-    if (this._disposed) return;
-    const delay = this._backoffMs;
-    this._backoffMs = Math.min(this._backoffMs * 2, 3e4);
-    setTimeout(() => {
-      if (!this._disposed) void this.connect();
-    }, delay);
-  }
-};
-async function fetchCentrifugoToken(endpoint, projectUuid, authToken, fetchImpl = fetch) {
-  const r = await fetchImpl(endpoint, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `ApiKey ${authToken}`
-    },
-    body: JSON.stringify({ project_uuid: projectUuid })
-  });
-  if (!r.ok) {
-    throw new Error(`centrifugo-token endpoint ${r.status}: ${await r.text()}`);
-  }
-  return await r.json();
-}
-
 // src/key-registry.ts
 var GLOBAL = "__verbumia_key_registry__";
 var SEP = "\0";
@@ -317,10 +214,10 @@ var VerbumiaI18n = class {
   fallbackLng;
   missingEvents = [];
   _bundles = /* @__PURE__ */ new Map();
-  // `${locale}/${ns}` -> tree
+  // `${version}/${locale}/${ns}` -> tree
   _attempted = /* @__PURE__ */ new Set();
-  // `${locale}/${ns}` keys we've fetched
-  // Tighter gate than `_attempted`: this set only contains (locale, ns)
+  // `${version}/${locale}/${ns}` keys we've fetched
+  // Tighter gate than `_attempted`: this set only contains (version, locale, ns)
   // pairs whose CDN response was 200 with at least one top-level key. An
   // empty bundle (404 → {} OR 200 → {}) is treated as "no data yet";
   // calling t() against a key in such a bundle does NOT fire reportMissing.
@@ -335,13 +232,20 @@ var VerbumiaI18n = class {
   // dedup `${locale}/${ns}/${key}` per-flush
   _timer = null;
   _listeners = /* @__PURE__ */ new Set();
-  _live = null;
   // Stable snapshot reference for useSyncExternalStore. Returning a fresh
   // object on each getSnapshot call would loop React forever — we rebuild
   // it ONLY in _notify (when state actually changed) and return the cached
   // reference between notifications.
   _snapshot;
   constructor(config) {
+    const removedRealtimeKeys = Object.keys(config).filter(
+      (k) => k === "liveUpdates" || k.startsWith("centrifugo")
+    );
+    if (removedRealtimeKeys.length > 0) {
+      throw new Error(
+        `@verbumia/react-i18next: ${removedRealtimeKeys.join(", ")} ${removedRealtimeKeys.length > 1 ? "were" : "was"} removed in 0.9.0 \u2014 realtime is now the @verbumia/realtime plugin. Remove them and pass \`plugins: [verbumiaRealtime({ wsUrl })]\` to <VerbumiaProvider> instead.`
+      );
+    }
     this.locale = config.defaultLocale;
     this.fallbackLng = config.fallbackLng;
     this._config = {
@@ -354,10 +258,7 @@ var VerbumiaI18n = class {
       flushIntervalMs: config.flushIntervalMs ?? DEFAULT_FLUSH_MS,
       flushBatchSize: config.flushBatchSize ?? DEFAULT_BATCH,
       missingEventsBufferSize: config.missingEventsBufferSize ?? DEFAULT_BUFFER,
-      versionSlug: config.versionSlug ?? DEFAULT_VERSION_SLUG,
-      liveUpdates: !!config.liveUpdates,
-      centrifugoTokenEndpoint: config.centrifugoTokenEndpoint ?? `${(config.apiBase ?? DEFAULT_API_BASE).replace(/\/+$/, "")}/v1/auth/centrifugo-token`,
-      centrifugoWsUrl: config.centrifugoWsUrl ?? "",
+      version: config.version ?? config.versionSlug ?? DEFAULT_VERSION_SLUG,
       env: config.env ?? "prod"
     };
     this._transport = config.transport ?? (this._config.missingHandler === "log" ? logTransport : defaultTransport({
@@ -384,9 +285,16 @@ var VerbumiaI18n = class {
       changeLanguage: this.changeLanguage,
       t: this.t,
       missingEvents: this.missingEvents,
-      flushMissing: this.flushMissing
+      flushMissing: this.flushMissing,
+      reload: this.reload
     };
   }
+  /** Bundle cache-key builder. Includes `version` so providers with
+   *  different `version` values never share cached bundles. The segments
+   *  (version/locale/ns) are slugs and never contain '/'. */
+  _bundleKey(locale, ns) {
+    return `${this._config.version}/${locale}/${ns}`;
+  }
   _notify() {
     this._snapshot = this._buildSnapshot();
     for (const l of this._listeners) l();
@@ -409,9 +317,6 @@ var VerbumiaI18n = class {
     );
     this.ready = true;
     this._startTimer();
-    if (this._config.liveUpdates && this._config.env === "dev") {
-      this._startLive(fetchImpl);
-    }
     this._notify();
   }
   setLocale = async (next) => {
@@ -437,97 +342,52 @@ var VerbumiaI18n = class {
       clearInterval(this._timer);
       this._timer = null;
     }
-    if (this._live) {
-      this._live.dispose();
-      this._live = null;
-    }
   }
   /**
-   * Start the Centrifugo subscription and re-fetch the relevant bundle on
-   * each `translations_published` event. Best-effort: if the WS URL or
-   * token endpoint isn't reachable, we log silently and the SDK continues
-   * to serve the initial bundle.
+   * Bust-refetch already-loaded bundles and re-render once. Generic
+   * replacement for the old realtime-only refetch: iterate the
+   * `_attempted` cache keys (`${version}/${locale}/${ns}`), optionally
+   * filtered by `opts.locale` / `opts.namespace`, and re-pull each one
+   * with `{ bust: true }` so the mutable CDN `latest/` alias bypasses the
+   * HTTP cache. After all settle, `_notify()` once so React re-renders.
+   *
+   * Used by `@verbumia/realtime` on a `translations_published` push and as
+   * a manual refresh hook. If nothing matches, returns without notifying.
    */
-  _startLive(fetchImpl) {
-    const wsUrl = this._config.centrifugoWsUrl;
-    if (!wsUrl) {
-      if (typeof console !== "undefined") {
-        console.warn(
-          "@verbumia/react-i18next: liveUpdates=true but centrifugoWsUrl is empty; skipping subscription."
-        );
-      }
-      return;
+  reload = async (opts = {}) => {
+    const targets = [];
+    for (const key of this._attempted) {
+      const parts = key.split("/");
+      const locale = parts[1];
+      const ns = parts[2];
+      if (!locale || !ns) continue;
+      if (opts.locale && opts.locale !== locale) continue;
+      if (opts.namespace && opts.namespace !== ns) continue;
+      targets.push({ locale, ns });
     }
-    const projectUuid = this._config.projectUuid;
-    const tokenEndpoint = this._config.centrifugoTokenEndpoint;
-    const apiToken = this._config.token;
-    const refreshToken = async () => {
-      const { token } = await fetchCentrifugoToken(
-        tokenEndpoint,
-        projectUuid,
-        apiToken,
-        fetchImpl
-      );
-      return token;
-    };
-    void (async () => {
-      let channel;
-      let token;
-      try {
-        const minted = await fetchCentrifugoToken(
-          tokenEndpoint,
-          projectUuid,
-          apiToken,
-          fetchImpl
-        );
-        channel = minted.channel;
-        token = minted.token;
-      } catch (err) {
-        if (typeof console !== "undefined") {
-          console.warn("@verbumia/react-i18next: live token mint failed", err);
-        }
-        return;
-      }
-      this._live = new LiveClient({
-        url: wsUrl,
-        token,
-        channel,
-        refreshToken,
-        onMessage: (data) => this._onLiveMessage(data, fetchImpl)
-      });
-      void this._live.connect();
-    })();
-  }
-  _onLiveMessage(data, fetchImpl) {
-    if (!data || typeof data !== "object") return;
-    const d = data;
-    if (d.event !== "translations_published") return;
-    const lang = d.language_code;
-    const ns = d.namespace_slug;
-    if (!lang || !ns) return;
-    const cacheKey = `${lang}/${ns}`;
-    if (!this._attempted.has(cacheKey)) return;
-    void this._loadBundle(lang, ns, fetchImpl, { bust: true }).then(() => {
-      this._notify();
-    });
-  }
+    if (targets.length === 0) return;
+    await Promise.all(
+      targets.map((t) => this._loadBundle(t.locale, t.ns, fetch, { bust: true }))
+    );
+    this._notify();
+  };
   // ---- Translation ----
   t = (key, optionsOrDefault, maybeOptions) => {
     const options = typeof optionsOrDefault === "string" ? { ...maybeOptions ?? {}, defaultValue: optionsOrDefault } : optionsOrDefault;
     const namespace = this._splitNamespace(key);
     const bareKey = namespace.bareKey;
     const ns = namespace.ns;
-    const fromActive = resolve(this._bundles.get(`${this.locale}/${ns}`), bareKey);
+    const fromActive = resolve(this._bundles.get(this._bundleKey(this.locale, ns)), bareKey);
     if (fromActive != null) {
       return this._render(fromActive, this.locale, options);
     }
     if (this.fallbackLng && this.fallbackLng !== this.locale) {
-      const fb = resolve(this._bundles.get(`${this.fallbackLng}/${ns}`), bareKey);
+      const fb = resolve(this._bundles.get(this._bundleKey(this.fallbackLng, ns)), bareKey);
       if (fb != null) {
         return this._render(fb, this.fallbackLng, options);
       }
     }
-    if (this.ready && this._attempted.has(`${this.locale}/${ns}`) && this._hasContent.has(`${this.locale}/${ns}`)) {
+    if (this.ready && this._attempted.has(this._bundleKey(this.locale, ns)) && this._hasContent.has(this._bundleKey(this.locale, ns))) {
       this._reportMissing({
         key: bareKey,
         namespace: ns,
@@ -574,13 +434,13 @@ var VerbumiaI18n = class {
     return { ns: this._config.namespaces[0], bareKey: key };
   }
   async _loadBundle(locale, ns, fetchImpl = fetch, opts = {}) {
-    const cacheKey = `${locale}/${ns}`;
+    const cacheKey = this._bundleKey(locale, ns);
     let url;
     let init;
     if (this._config.env === "dev") {
       const params = new URLSearchParams({ language: locale, namespace: ns });
-      if (this._config.versionSlug && this._config.versionSlug !== "main") {
-        params.set("version_slug", this._config.versionSlug);
+      if (this._config.version && this._config.version !== "main") {
+        params.set("version_slug", this._config.version);
       }
       url = `${this._config.apiBase.replace(/\/+$/, "")}/v1/projects/${this._config.projectUuid}/translations/runtime?${params.toString()}`;
       init = {
@@ -589,7 +449,7 @@ var VerbumiaI18n = class {
         credentials: "omit"
       };
     } else {
-      url = `${this._config.cdnBase.replace(/\/+$/, "")}/p/${this._config.projectUuid}/${this._config.versionSlug}/latest/${locale}/${ns}.json`;
+      url = `${this._config.cdnBase.replace(/\/+$/, "")}/p/${this._config.projectUuid}/${this._config.version}/latest/${locale}/${ns}.json`;
       init = { method: "GET", credentials: "omit" };
     }
     if (opts.bust) {
@@ -631,25 +491,27 @@ var VerbumiaI18n = class {
   /**
    * Resolve the `source_value` we send with a missing-key report.
    *
-   * Fallback chain (per backend agreement 2026-05-14, task 575):
+   * Fallback chain (Option A, task #746 — backend ingest aligned):
    *   1. `options.defaultValue` — explicit developer-provided string.
    *   2. The fallbackLng bundle's value for this key (typically the
    *      source/canonical locale). Only used when it resolves to a
    *      plain string, not a plural CLDR dict.
-   *   3. The bare key itself — last resort so dashboards never render
-   *      a blank `source_value` column.
+   *   3. Otherwise `undefined` — we DO NOT fall back to the key name (that
+   *      made the column unusable: a placeholder indistinguishable from a
+   *      real default). The key is already carried in `event.key`; an absent
+   *      `source_value` is the signal that there is no promotable value.
    */
   _sourceValueFor(bareKey, ns, options) {
     if (typeof options?.defaultValue === "string") {
       return options.defaultValue;
     }
     if (this.fallbackLng && this.fallbackLng !== this.locale) {
-      const fb = resolve(this._bundles.get(`${this.fallbackLng}/${ns}`), bareKey);
+      const fb = resolve(this._bundles.get(this._bundleKey(this.fallbackLng, ns)), bareKey);
       if (typeof fb === "string") {
         return fb;
       }
     }
-    return bareKey;
+    return void 0;
   }
   _reportMissing(event) {
     if (this._config.missingHandler === "off") return;