@verbumia/react-i18next 0.8.0 → 0.9.1

package/dist/index.js

@@ -10,7 +10,7 @@ import {
 
 // 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;
@@ -20,7 +20,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,
@@ -50,111 +52,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";
@@ -292,10 +189,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.
@@ -310,13 +207,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 = {
@@ -329,10 +233,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({
@@ -359,9 +260,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();
@@ -384,9 +292,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) => {
@@ -412,97 +317,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,
@@ -549,13 +409,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 = {
@@ -564,7 +424,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) {
@@ -606,25 +466,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;