@lionrapid/core 0.6.0 → 0.6.2

package/dist/browser/lionrapid.auto.dev.js

@@ -2766,6 +2766,7 @@ var __lionrapidAutoExports = (() => {
       // 🔥 EMBEDDED: Core integration maps
       __publicField(this, "formatters", /* @__PURE__ */ new Map());
       __publicField(this, "processors", /* @__PURE__ */ new Map());
+      __publicField(this, "warnedNoInterpolate", false);
       // 📡 EVENT-DRIVEN: Just track for cleanup
       __publicField(this, "eventPlugins", /* @__PURE__ */ new Set());
       // 📦 CONTENT: Parser and serializer for ContentUnit processing
@@ -3058,6 +3059,11 @@ var __lionrapidAutoExports = (() => {
             resolvedLocale,
             resolvedKey
           );
+        } else if (!this.warnedNoInterpolate && params && Object.keys(params).length > 0 && processedValue.includes("{")) {
+          this.warnedNoInterpolate = true;
+          console.warn(
+            "[LionRapid] Translation params were passed but no interpolate formatter is registered \u2014 {placeholders} render literally. Install @lionrapid/formatters and add .use(coreFormattersPlugin) to the builder."
+          );
         }
         if (this.processors.size > 0) {
           for (const [name, processor] of this.processors.entries()) {
@@ -3838,6 +3844,31 @@ var __lionrapidAutoExports = (() => {
        * and payload can never desync because they live and die together.
        */
       __publicField(this, "namespaceSnapshots", /* @__PURE__ */ new Map());
+      /**
+       * Miss-path flood protection (READINESS before-scale #1: one cold locale
+       * switch measured ~380 requests in 10 s — every t() miss refired a key GET
+       * and a namespace GET on every re-render, forever on animated pages).
+       */
+      /** GETs currently on the wire, keyed by `url|if-none-match` — identical
+       *  concurrent requests share one fetch; each awaiter gets a clone. The
+       *  If-None-Match value is part of the key so the 304-without-snapshot
+       *  unconditional refetch never coalesces onto a conditional flight. */
+      __publicField(this, "inflightGets", /* @__PURE__ */ new Map());
+      /** URL → 404/423 seen recently: repeats are answered locally (same typed
+       *  error, no network) until `until`. 423 honors the server's Retry-After.
+       *  Cleared entirely by any successful write — discovery sync keeps its
+       *  miss → batch → served-back round-trip. */
+      __publicField(this, "negativeCache", /* @__PURE__ */ new Map());
+      /** One-way latch: a 401 anywhere (or a 403 on a READ) means the key is
+       *  wrong or unauthorized for this project, and retrying cannot heal it —
+       *  after the first one nothing touches the network again for this
+       *  instance (a page reload starts fresh). Holds the status that tripped
+       *  it so short-circuits answer honestly. */
+      __publicField(this, "authFailedStatus", null);
+      /** Write-only latch (auth-byok Phase 18): a 403 (scope) or 429 (quota) on
+       *  a WRITE degrades this instance to read-only — writes stop, silently
+       *  and without retries, while reads keep serving the page. */
+      __publicField(this, "writesFailedStatus", null);
       /**
        * Default endpoint templates with placeholder support
        * Placeholders: :key, :locale, :namespace
@@ -3845,6 +3876,7 @@ var __lionrapidAutoExports = (() => {
       __publicField(this, "DEFAULT_ENDPOINTS", {
         getTranslation: "/api/integrations/translations/:key",
         getNamespace: "/api/integrations/translations/:locale/:namespace",
+        getProjectConfig: "/api/integrations/project-config",
         setTranslation: "/api/integrations/sync/:key",
         setNamespace: "/api/integrations/sync/:locale/:namespace",
         setBatch: "/api/integrations/sync/batch",
@@ -3956,6 +3988,40 @@ var __lionrapidAutoExports = (() => {
         this.handleCaughtError(error);
       }
     }
+    /**
+     * Project-level config for this key — the dashboard's language list,
+     * served under the same trust model as translation reads (docs/20,
+     * companion track). Returns null when the server doesn't expose the
+     * endpoint (404 — older server, feature not deployed) or the payload is
+     * unusable: absence means "keep your local fallback", never an error.
+     */
+    async getProjectConfig() {
+      if (!this.config?.options?.baseUrl) {
+        throw new NetworkError("API base URL is not set");
+      }
+      const url = this.buildUrl("getProjectConfig", {});
+      logger.debug(`API GET ProjectConfig: ${url}`);
+      try {
+        const response = await this.makeRequest(url, "GET");
+        if (response.status === 404) {
+          return null;
+        }
+        if (!response.ok) {
+          this.handleHttpError(response, "project-config");
+        }
+        const data = await response.json();
+        if (!data || typeof data.defaultLocale !== "string" || !Array.isArray(data.languages)) {
+          logger.warn("project-config payload unusable \u2014 keeping local fallback");
+          return null;
+        }
+        return {
+          defaultLocale: data.defaultLocale,
+          languages: data.languages.map(String)
+        };
+      } catch (error) {
+        this.handleCaughtError(error);
+      }
+    }
     /**
      * Shared namespace fetch with the canonical 304 contract:
      * - If-None-Match is sent ONLY when a snapshot (version + payload) is in hand.
@@ -4280,7 +4346,87 @@ var __lionrapidAutoExports = (() => {
     /**
      * Make HTTP request with timeout and headers
      */
-    async makeRequest(url, method, body, extraHeaders) {
+    makeRequest(url, method, body, extraHeaders) {
+      if (this.authFailedStatus !== null) {
+        return Promise.resolve(
+          new Response(null, {
+            status: this.authFailedStatus,
+            statusText: `auth latched off after ${this.authFailedStatus}`
+          })
+        );
+      }
+      if (method !== "GET") {
+        if (this.writesFailedStatus !== null) {
+          return Promise.resolve(
+            new Response(null, {
+              status: this.writesFailedStatus,
+              statusText: `writes latched off after ${this.writesFailedStatus}`
+            })
+          );
+        }
+        return this.doFetch(url, method, body, extraHeaders).then(
+          (resp) => this.recordOutcome(url, method, resp)
+        );
+      }
+      const negative = this.negativeCache.get(url);
+      if (negative) {
+        if (Date.now() < negative.until) {
+          logger.debug(`Negative-cache hit (${negative.status}): ${url}`);
+          const headers = negative.status === 423 ? { "Retry-After": String(Math.ceil((negative.until - Date.now()) / 1e3)) } : void 0;
+          return Promise.resolve(
+            new Response(null, { status: negative.status, statusText: "negative cache", headers })
+          );
+        }
+        this.negativeCache.delete(url);
+      }
+      const flightKey = `${url}|${extraHeaders?.["If-None-Match"] ?? ""}`;
+      const existing = this.inflightGets.get(flightKey);
+      if (existing) {
+        return existing.then((resp) => this.cloneResponse(resp));
+      }
+      const flight = this.doFetch(url, method, body, extraHeaders).then((resp) => this.recordOutcome(url, method, resp)).finally(() => this.inflightGets.delete(flightKey));
+      this.inflightGets.set(flightKey, flight);
+      return flight.then((resp) => this.cloneResponse(resp));
+    }
+    /** Bookkeeping on every real (non-synthesized) response — runs once per
+     *  physical fetch, never once per coalesced awaiter. */
+    recordOutcome(url, method, response) {
+      const status = response.status;
+      if (status === 401 || status === 403 && method === "GET") {
+        if (this.authFailedStatus === null) {
+          this.authFailedStatus = status;
+          console.warn(
+            `[LionRapid] API key rejected (${status}) \u2014 network translations are disabled for this session. Fix the key and reload; retrying cannot heal an auth failure.`
+          );
+        }
+        return response;
+      }
+      if ((status === 403 || status === 429) && method !== "GET") {
+        if (this.writesFailedStatus === null) {
+          this.writesFailedStatus = status;
+          logger.warn(
+            `Write path disabled after ${status} (scope/quota) \u2014 running read-only`
+          );
+        }
+        return response;
+      }
+      if (method === "GET" && (status === 404 || status === 423)) {
+        const retryAfterSec = status === 423 ? Number(response.headers?.get?.("Retry-After")) : NaN;
+        const ttl = Number.isFinite(retryAfterSec) && retryAfterSec > 0 ? retryAfterSec * 1e3 : this.config.options?.negativeCacheTtlMs ?? _NetworkRepository.DEFAULT_NEGATIVE_TTL_MS;
+        this.negativeCache.set(url, { status, until: Date.now() + ttl });
+      } else if (method !== "GET" && response.ok) {
+        this.negativeCache.clear();
+      } else if (method === "GET" && response.ok) {
+        this.negativeCache.delete(url);
+      }
+      return response;
+    }
+    /** Test doubles (and exotic runtimes) hand us plain objects — only real
+     *  Responses need cloning so each coalesced awaiter can read the body. */
+    cloneResponse(response) {
+      return typeof response.clone === "function" ? response.clone() : response;
+    }
+    async doFetch(url, method, body, extraHeaders) {
       const controller = new AbortController();
       const timeout = this.config.options?.timeout ?? 1e4;
       const timeoutId = setTimeout(
@@ -4313,6 +4459,7 @@ var __lionrapidAutoExports = (() => {
   /** Legacy bare-version prefix — a version WITHOUT its payload is exactly the
    *  desync the snapshot store exists to prevent; entries are deleted on sight. */
   __publicField(_NetworkRepository, "LEGACY_VERSION_PREFIX", "lionrapid:v:");
+  __publicField(_NetworkRepository, "DEFAULT_NEGATIVE_TTL_MS", 6e4);
   var NetworkRepository = _NetworkRepository;
 
   // src/browser/exclude-filter.ts
@@ -5555,9 +5702,11 @@ var __lionrapidAutoExports = (() => {
       this.config = {
         enabled: config.enabled ?? true,
         priority: config.priority ?? 0,
+        // Use build sequence by default
         options: {
           prefix: config.options?.prefix ?? STORAGE_PREFIX,
           ttl: config.options?.ttl ?? 24 * 60 * 60 * 1e3,
+          // 24 hours default
           maxSize: config.options?.maxSize ?? 500,
           ...config.options
         }
@@ -5570,6 +5719,10 @@ var __lionrapidAutoExports = (() => {
         this.migrateIfNeeded();
       }
     }
+    /**
+     * Check if localStorage is available
+     * Returns false in SSR, private browsing, or when quota is 0
+     */
     checkAvailability() {
       if (typeof window === "undefined") {
         return false;
@@ -5583,6 +5736,9 @@ var __lionrapidAutoExports = (() => {
         return false;
       }
     }
+    /**
+     * Handle version migrations - clear cache when version changes
+     */
     migrateIfNeeded() {
       try {
         const storedVersion = window.localStorage.getItem(VERSION_KEY);
@@ -5593,6 +5749,10 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Get a translation value by key
+     * Returns null if not found or expired
+     */
     get(key) {
       if (!this.available) return null;
       try {
@@ -5609,6 +5769,10 @@ var __lionrapidAutoExports = (() => {
         return null;
       }
     }
+    /**
+     * Set a translation value
+     * Automatically handles quota exceeded by evicting oldest entries
+     */
     set(key, value) {
       if (!this.available) return;
       const fullKey = this.prefix + key;
@@ -5633,6 +5797,9 @@ var __lionrapidAutoExports = (() => {
         }
       }
     }
+    /**
+     * Remove a translation by key
+     */
     remove(key) {
       if (!this.available) return;
       try {
@@ -5640,6 +5807,10 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Clear all LionRapid entries from localStorage
+     * Preserves entries from other applications
+     */
     clear() {
       if (!this.available) return;
       try {
@@ -5654,6 +5825,9 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Clear all entries for a specific namespace
+     */
     clearNamespace(locale, namespace) {
       if (!this.available) return;
       const namespaceCacheKey = `@${locale}:${namespace}`;
@@ -5672,6 +5846,9 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Get namespace translations
+     */
     getNamespace(locale, namespace) {
       const namespaceCacheKey = `@${locale}:${namespace}`;
       const value = this.get(namespaceCacheKey);
@@ -5683,10 +5860,16 @@ var __lionrapidAutoExports = (() => {
         return null;
       }
     }
+    /**
+     * Set namespace translations
+     */
     setNamespace(locale, namespace, translations) {
       const namespaceCacheKey = `@${locale}:${namespace}`;
       this.set(namespaceCacheKey, JSON.stringify(translations));
     }
+    /**
+     * Get all cache entries for debugging
+     */
     getEntries() {
       const entries = {};
       if (!this.available) return entries;
@@ -5706,12 +5889,21 @@ var __lionrapidAutoExports = (() => {
       }
       return entries;
     }
+    /**
+     * Get repository configuration
+     */
     getConfig() {
       return this.config;
     }
+    /**
+     * Check if localStorage is available
+     */
     isAvailable() {
       return this.available;
     }
+    /**
+     * Get the number of entries in the cache
+     */
     getEntryCount() {
       if (!this.available) return 0;
       let count = 0;
@@ -5726,12 +5918,18 @@ var __lionrapidAutoExports = (() => {
       }
       return count;
     }
+    /**
+     * Check if error is a quota exceeded error
+     */
     isQuotaError(error) {
       if (error instanceof DOMException) {
         return error.name === "QuotaExceededError" || error.name === "NS_ERROR_DOM_QUOTA_REACHED";
       }
       return false;
     }
+    /**
+     * Evict oldest 25% of entries when quota is exceeded
+     */
     evictOldest() {
       if (!this.available) return;
       try {
@@ -5759,6 +5957,9 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Get cache statistics
+     */
     getCacheStats() {
       const size = this.getEntryCount();
       const usage = this.maxSize > 0 ? `${Math.round(size / this.maxSize * 100)}%` : "0%";
@@ -5772,7 +5973,7 @@ var __lionrapidAutoExports = (() => {
 
   // src/browser/storage/cache-storage-repository.ts
   var CACHE_NAME = "lionrapid-v1";
-  var CACHE_PREFIX = "lionrapid:";
+  var CACHE_PREFIX = "https://cache.lionrapid.internal/";
   var CacheStorageRepository = class {
     constructor(config = {}) {
       __publicField(this, "name", "CacheStorageRepository");
@@ -5787,6 +5988,7 @@ var __lionrapidAutoExports = (() => {
         options: {
           cacheName: config.options?.cacheName ?? CACHE_NAME,
           ttl: config.options?.ttl ?? 7 * 24 * 60 * 60 * 1e3,
+          // 7 days default
           ...config.options
         }
       };
@@ -5794,9 +5996,17 @@ var __lionrapidAutoExports = (() => {
       this.defaultTTL = this.config.options?.ttl ?? 7 * 24 * 60 * 60 * 1e3;
       this.available = this.checkAvailability();
     }
+    /**
+     * Check if Cache API is available
+     * Returns false in SSR, old browsers, or insecure contexts
+     */
     checkAvailability() {
       return typeof caches !== "undefined";
     }
+    /**
+     * Get a translation value by key
+     * @throws {TranslationNotFoundError} When translation doesn't exist or is expired
+     */
     async get(key) {
       if (!this.available) {
         throw new TranslationNotFoundError(key);
@@ -5820,6 +6030,9 @@ var __lionrapidAutoExports = (() => {
         throw new TranslationNotFoundError(key);
       }
     }
+    /**
+     * Set a translation value
+     */
     async set(key, value) {
       if (!this.available) return;
       try {
@@ -5838,6 +6051,9 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Remove a translation by key
+     */
     async remove(key) {
       if (!this.available) return;
       try {
@@ -5846,6 +6062,9 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Clear all LionRapid entries from the cache
+     */
     async clear() {
       if (!this.available) return;
       try {
@@ -5857,6 +6076,9 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Clear all entries for a specific namespace
+     */
     async clearNamespace(locale, namespace) {
       if (!this.available) return;
       const namespaceCacheKey = `@${locale}:${namespace}`;
@@ -5874,6 +6096,10 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Get namespace translations
+     * @throws {TranslationNotFoundError} When namespace doesn't exist
+     */
     async getNamespace(locale, namespace) {
       const namespaceCacheKey = `@${locale}:${namespace}`;
       const value = await this.get(namespaceCacheKey);
@@ -5884,16 +6110,29 @@ var __lionrapidAutoExports = (() => {
         throw new TranslationNotFoundError(namespaceCacheKey);
       }
     }
+    /**
+     * Set namespace translations
+     */
     async setNamespace(locale, namespace, translations) {
       const namespaceCacheKey = `@${locale}:${namespace}`;
       await this.set(namespaceCacheKey, JSON.stringify(translations));
     }
+    /**
+     * Get repository configuration
+     */
     getConfig() {
       return this.config;
     }
+    /**
+     * Check if Cache API is available
+     */
     isAvailable() {
       return this.available;
     }
+    /**
+     * Get all cached entries (for debugging)
+     * Returns an object mapping keys to values
+     */
     async getEntries() {
       const entries = {};
       if (!this.available) return entries;
@@ -5916,6 +6155,9 @@ var __lionrapidAutoExports = (() => {
       }
       return entries;
     }
+    /**
+     * Get cache statistics
+     */
     async getCacheStats() {
       if (!this.available) {
         return { size: 0, cacheName: this.cacheName };
@@ -5935,8 +6177,9 @@ var __lionrapidAutoExports = (() => {
   function resolveWritePolicy(apiKey) {
     const isPublishable = apiKey.startsWith("pk_");
     return {
+      bootNetwork: isPublishable,
       syncMissing: { enabled: isPublishable },
-      warnReadOnly: !isPublishable
+      warnRefused: !isPublishable
     };
   }
   function configForWindow(config) {
@@ -6013,7 +6256,7 @@ var __lionrapidAutoExports = (() => {
   function readLocaleCookie(availableLanguages) {
     if (typeof document === "undefined") return null;
     const match = document.cookie.match(
-      /lionrapid_locale=([a-z]{2,3}(?:-[a-z0-9]{2,4})*)/i
+      /(?:^|;\s*)lionrapid_locale=([a-z]{2,3}(?:-[a-z0-9]{2,4})*)/i
     );
     if (!match) return null;
     return matchLocale([match[1]], availableLanguages, "") || null;
@@ -6059,9 +6302,21 @@ var __lionrapidAutoExports = (() => {
       document.documentElement.dir = localeDir(locale);
     }
   }
-  async function autoInit() {
+  function findConfigScript() {
+    const current = document.currentScript;
+    if (current instanceof HTMLScriptElement && current.dataset.apiKey) {
+      return current;
+    }
     const scripts = document.querySelectorAll("script[data-api-key]");
-    const script = scripts[scripts.length - 1];
+    if (scripts.length > 1) {
+      console.warn(
+        `[LionRapid] ${scripts.length} script tags with data-api-key found; using the last one`
+      );
+    }
+    return scripts[scripts.length - 1];
+  }
+  async function autoInit() {
+    const script = findConfigScript();
     if (!script) {
       console.warn("[LionRapid] No script tag with data-api-key found");
       return;
@@ -6073,9 +6328,9 @@ var __lionrapidAutoExports = (() => {
       return;
     }
     const writePolicy = resolveWritePolicy(config.apiKey);
-    if (writePolicy.warnReadOnly) {
+    if (writePolicy.warnRefused) {
       console.error(
-        "[LionRapid] data-api-key must be a publishable pk_ key; running read-only"
+        "[LionRapid] data-api-key must be a publishable pk_ key \u2014 network translations are disabled. Copy the snippet from the integration hub to get the pk_ key for this project."
       );
     }
     const initialLocale = resolveInitialLocale(config);
@@ -6129,25 +6384,28 @@ var __lionrapidAutoExports = (() => {
           })
         );
       }
-      const core = await builder.use(
-        new NetworkRepository({
-          enabled: true,
-          options: {
-            baseUrl: config.baseUrl,
-            apiKey: config.apiKey,
-            // pk_ keys sync missing source strings (discovery); anything else
-            // runs read-only — see resolveWritePolicy.
-            syncMissing: writePolicy.syncMissing,
-            preloadNamespaces: [
-              {
-                locale: initialLocale,
-                namespace: config.namespace,
-                eager: true
-              }
-            ]
-          }
-        })
-      ).build();
+      if (writePolicy.bootNetwork) {
+        builder.use(
+          new NetworkRepository({
+            enabled: true,
+            options: {
+              baseUrl: config.baseUrl,
+              apiKey: config.apiKey,
+              // pk_ keys sync missing source strings (discovery) — see
+              // resolveWritePolicy.
+              syncMissing: writePolicy.syncMissing,
+              preloadNamespaces: [
+                {
+                  locale: initialLocale,
+                  namespace: config.namespace,
+                  eager: true
+                }
+              ]
+            }
+          })
+        );
+      }
+      const core = await builder.build();
       const autoTranslator = new AutoTranslator({
         excludeSelectors: config.excludeSelectors
       });