@lionrapid/core 0.6.1 → 0.6.3

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

@@ -3962,6 +3962,8 @@ var LionRapid = (() => {
   };
 
   // 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");
@@ -3977,6 +3979,31 @@ var LionRapid = (() => {
        * 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
@@ -3984,6 +4011,7 @@ var LionRapid = (() => {
       __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",
@@ -4095,6 +4123,40 @@ var LionRapid = (() => {
         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.
@@ -4419,7 +4481,87 @@ var LionRapid = (() => {
     /**
      * 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(
@@ -4429,6 +4571,7 @@ var LionRapid = (() => {
       try {
         const headers = {
           "Content-Type": "application/json",
+          [SURFACE_HEADER]: SURFACE_TAG,
           ...this.config.options?.headers,
           ...extraHeaders
         };
@@ -4452,6 +4595,7 @@ var LionRapid = (() => {
   /** 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/content/validator/ContentValidator.ts
@@ -5050,9 +5194,11 @@ var LionRapid = (() => {
       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
         }
@@ -5065,6 +5211,10 @@ var LionRapid = (() => {
         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;
@@ -5078,6 +5228,9 @@ var LionRapid = (() => {
         return false;
       }
     }
+    /**
+     * Handle version migrations - clear cache when version changes
+     */
     migrateIfNeeded() {
       try {
         const storedVersion = window.localStorage.getItem(VERSION_KEY);
@@ -5088,6 +5241,10 @@ var LionRapid = (() => {
       } catch {
       }
     }
+    /**
+     * Get a translation value by key
+     * Returns null if not found or expired
+     */
     get(key) {
       if (!this.available) return null;
       try {
@@ -5104,6 +5261,10 @@ var LionRapid = (() => {
         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;
@@ -5128,6 +5289,9 @@ var LionRapid = (() => {
         }
       }
     }
+    /**
+     * Remove a translation by key
+     */
     remove(key) {
       if (!this.available) return;
       try {
@@ -5135,6 +5299,10 @@ var LionRapid = (() => {
       } catch {
       }
     }
+    /**
+     * Clear all LionRapid entries from localStorage
+     * Preserves entries from other applications
+     */
     clear() {
       if (!this.available) return;
       try {
@@ -5149,6 +5317,9 @@ var LionRapid = (() => {
       } catch {
       }
     }
+    /**
+     * Clear all entries for a specific namespace
+     */
     clearNamespace(locale, namespace) {
       if (!this.available) return;
       const namespaceCacheKey = `@${locale}:${namespace}`;
@@ -5167,6 +5338,9 @@ var LionRapid = (() => {
       } catch {
       }
     }
+    /**
+     * Get namespace translations
+     */
     getNamespace(locale, namespace) {
       const namespaceCacheKey = `@${locale}:${namespace}`;
       const value = this.get(namespaceCacheKey);
@@ -5178,10 +5352,16 @@ var LionRapid = (() => {
         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;
@@ -5201,12 +5381,21 @@ var LionRapid = (() => {
       }
       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;
@@ -5221,12 +5410,18 @@ var LionRapid = (() => {
       }
       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 {
@@ -5254,6 +5449,9 @@ var LionRapid = (() => {
       } catch {
       }
     }
+    /**
+     * Get cache statistics
+     */
     getCacheStats() {
       const size = this.getEntryCount();
       const usage = this.maxSize > 0 ? `${Math.round(size / this.maxSize * 100)}%` : "0%";
@@ -5267,7 +5465,7 @@ var LionRapid = (() => {
 
   // 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");
@@ -5282,6 +5480,7 @@ var LionRapid = (() => {
         options: {
           cacheName: config.options?.cacheName ?? CACHE_NAME,
           ttl: config.options?.ttl ?? 7 * 24 * 60 * 60 * 1e3,
+          // 7 days default
           ...config.options
         }
       };
@@ -5289,9 +5488,17 @@ var LionRapid = (() => {
       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);
@@ -5315,6 +5522,9 @@ var LionRapid = (() => {
         throw new TranslationNotFoundError(key);
       }
     }
+    /**
+     * Set a translation value
+     */
     async set(key, value) {
       if (!this.available) return;
       try {
@@ -5333,6 +5543,9 @@ var LionRapid = (() => {
       } catch {
       }
     }
+    /**
+     * Remove a translation by key
+     */
     async remove(key) {
       if (!this.available) return;
       try {
@@ -5341,6 +5554,9 @@ var LionRapid = (() => {
       } catch {
       }
     }
+    /**
+     * Clear all LionRapid entries from the cache
+     */
     async clear() {
       if (!this.available) return;
       try {
@@ -5352,6 +5568,9 @@ var LionRapid = (() => {
       } catch {
       }
     }
+    /**
+     * Clear all entries for a specific namespace
+     */
     async clearNamespace(locale, namespace) {
       if (!this.available) return;
       const namespaceCacheKey = `@${locale}:${namespace}`;
@@ -5369,6 +5588,10 @@ var LionRapid = (() => {
       } 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);
@@ -5379,16 +5602,29 @@ var LionRapid = (() => {
         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;
@@ -5411,6 +5647,9 @@ var LionRapid = (() => {
       }
       return entries;
     }
+    /**
+     * Get cache statistics
+     */
     async getCacheStats() {
       if (!this.available) {
         return { size: 0, cacheName: this.cacheName };