@lionrapid/core 0.6.1 → 0.6.3

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

@@ -3829,6 +3829,8 @@ var __lionrapidAutoExports = (() => {
   };
 
   // src/repositories/network-repository.ts
+  var SURFACE_HEADER = "X-LR-Surface";
+  var SURFACE_TAG = "snippet";
   var _NetworkRepository = class _NetworkRepository {
     constructor(config = {}) {
       __publicField(this, "name", "NetworkRepository");
@@ -3844,6 +3846,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
@@ -3851,6 +3878,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",
@@ -3962,6 +3990,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.
@@ -4286,7 +4348,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(
@@ -4296,6 +4438,7 @@ var __lionrapidAutoExports = (() => {
       try {
         const headers = {
           "Content-Type": "application/json",
+          [SURFACE_HEADER]: SURFACE_TAG,
           ...this.config.options?.headers,
           ...extraHeaders
         };
@@ -4319,6 +4462,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
@@ -5561,9 +5705,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
         }
@@ -5576,6 +5722,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;
@@ -5589,6 +5739,9 @@ var __lionrapidAutoExports = (() => {
         return false;
       }
     }
+    /**
+     * Handle version migrations - clear cache when version changes
+     */
     migrateIfNeeded() {
       try {
         const storedVersion = window.localStorage.getItem(VERSION_KEY);
@@ -5599,6 +5752,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 {
@@ -5615,6 +5772,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;
@@ -5639,6 +5800,9 @@ var __lionrapidAutoExports = (() => {
         }
       }
     }
+    /**
+     * Remove a translation by key
+     */
     remove(key) {
       if (!this.available) return;
       try {
@@ -5646,6 +5810,10 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Clear all LionRapid entries from localStorage
+     * Preserves entries from other applications
+     */
     clear() {
       if (!this.available) return;
       try {
@@ -5660,6 +5828,9 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Clear all entries for a specific namespace
+     */
     clearNamespace(locale, namespace) {
       if (!this.available) return;
       const namespaceCacheKey = `@${locale}:${namespace}`;
@@ -5678,6 +5849,9 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Get namespace translations
+     */
     getNamespace(locale, namespace) {
       const namespaceCacheKey = `@${locale}:${namespace}`;
       const value = this.get(namespaceCacheKey);
@@ -5689,10 +5863,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;
@@ -5712,12 +5892,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;
@@ -5732,12 +5921,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 {
@@ -5765,6 +5960,9 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Get cache statistics
+     */
     getCacheStats() {
       const size = this.getEntryCount();
       const usage = this.maxSize > 0 ? `${Math.round(size / this.maxSize * 100)}%` : "0%";
@@ -5778,7 +5976,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");
@@ -5793,6 +5991,7 @@ var __lionrapidAutoExports = (() => {
         options: {
           cacheName: config.options?.cacheName ?? CACHE_NAME,
           ttl: config.options?.ttl ?? 7 * 24 * 60 * 60 * 1e3,
+          // 7 days default
           ...config.options
         }
       };
@@ -5800,9 +5999,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);
@@ -5826,6 +6033,9 @@ var __lionrapidAutoExports = (() => {
         throw new TranslationNotFoundError(key);
       }
     }
+    /**
+     * Set a translation value
+     */
     async set(key, value) {
       if (!this.available) return;
       try {
@@ -5844,6 +6054,9 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Remove a translation by key
+     */
     async remove(key) {
       if (!this.available) return;
       try {
@@ -5852,6 +6065,9 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Clear all LionRapid entries from the cache
+     */
     async clear() {
       if (!this.available) return;
       try {
@@ -5863,6 +6079,9 @@ var __lionrapidAutoExports = (() => {
       } catch {
       }
     }
+    /**
+     * Clear all entries for a specific namespace
+     */
     async clearNamespace(locale, namespace) {
       if (!this.available) return;
       const namespaceCacheKey = `@${locale}:${namespace}`;
@@ -5880,6 +6099,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);
@@ -5890,16 +6113,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;
@@ -5922,6 +6158,9 @@ var __lionrapidAutoExports = (() => {
       }
       return entries;
     }
+    /**
+     * Get cache statistics
+     */
     async getCacheStats() {
       if (!this.available) {
         return { size: 0, cacheName: this.cacheName };
@@ -5941,8 +6180,9 @@ var __lionrapidAutoExports = (() => {
   function resolveWritePolicy(apiKey) {
     const isPublishable = apiKey.startsWith("pk_");
     return {
+      bootNetwork: isPublishable,
       syncMissing: { enabled: isPublishable },
-      warnReadOnly: !isPublishable
+      warnRefused: !isPublishable
     };
   }
   function configForWindow(config) {
@@ -6091,9 +6331,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);
@@ -6147,25 +6387,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
       });