@lionrapid/core 0.6.1 → 0.6.3

package/dist/browser/lionrapid.umd.js

@@ -3974,6 +3974,8 @@ var LionRapidBuilder = class _LionRapidBuilder {
 };
 
 // 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");
@@ -3989,6 +3991,31 @@ var _NetworkRepository = class _NetworkRepository {
      * 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
@@ -3996,6 +4023,7 @@ var _NetworkRepository = class _NetworkRepository {
     __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",
@@ -4107,6 +4135,40 @@ var _NetworkRepository = class _NetworkRepository {
       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.
@@ -4431,7 +4493,87 @@ var _NetworkRepository = class _NetworkRepository {
   /**
    * 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(
@@ -4441,6 +4583,7 @@ var _NetworkRepository = class _NetworkRepository {
     try {
       const headers = {
         "Content-Type": "application/json",
+        [SURFACE_HEADER]: SURFACE_TAG,
         ...this.config.options?.headers,
         ...extraHeaders
       };
@@ -4464,6 +4607,7 @@ __publicField(_NetworkRepository, "SNAPSHOT_PREFIX", "lionrapid:ns:");
 /** 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
@@ -5062,9 +5206,11 @@ var LocalStorageRepository = class {
     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
       }
@@ -5077,6 +5223,10 @@ var LocalStorageRepository = class {
       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;
@@ -5090,6 +5240,9 @@ var LocalStorageRepository = class {
       return false;
     }
   }
+  /**
+   * Handle version migrations - clear cache when version changes
+   */
   migrateIfNeeded() {
     try {
       const storedVersion = window.localStorage.getItem(VERSION_KEY);
@@ -5100,6 +5253,10 @@ var LocalStorageRepository = class {
     } catch {
     }
   }
+  /**
+   * Get a translation value by key
+   * Returns null if not found or expired
+   */
   get(key) {
     if (!this.available) return null;
     try {
@@ -5116,6 +5273,10 @@ var LocalStorageRepository = class {
       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;
@@ -5140,6 +5301,9 @@ var LocalStorageRepository = class {
       }
     }
   }
+  /**
+   * Remove a translation by key
+   */
   remove(key) {
     if (!this.available) return;
     try {
@@ -5147,6 +5311,10 @@ var LocalStorageRepository = class {
     } catch {
     }
   }
+  /**
+   * Clear all LionRapid entries from localStorage
+   * Preserves entries from other applications
+   */
   clear() {
     if (!this.available) return;
     try {
@@ -5161,6 +5329,9 @@ var LocalStorageRepository = class {
     } catch {
     }
   }
+  /**
+   * Clear all entries for a specific namespace
+   */
   clearNamespace(locale, namespace) {
     if (!this.available) return;
     const namespaceCacheKey = `@${locale}:${namespace}`;
@@ -5179,6 +5350,9 @@ var LocalStorageRepository = class {
     } catch {
     }
   }
+  /**
+   * Get namespace translations
+   */
   getNamespace(locale, namespace) {
     const namespaceCacheKey = `@${locale}:${namespace}`;
     const value = this.get(namespaceCacheKey);
@@ -5190,10 +5364,16 @@ var LocalStorageRepository = class {
       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;
@@ -5213,12 +5393,21 @@ var LocalStorageRepository = class {
     }
     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;
@@ -5233,12 +5422,18 @@ var LocalStorageRepository = class {
     }
     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 {
@@ -5266,6 +5461,9 @@ var LocalStorageRepository = class {
     } catch {
     }
   }
+  /**
+   * Get cache statistics
+   */
   getCacheStats() {
     const size = this.getEntryCount();
     const usage = this.maxSize > 0 ? `${Math.round(size / this.maxSize * 100)}%` : "0%";
@@ -5279,7 +5477,7 @@ var LocalStorageRepository = class {
 
 // 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");
@@ -5294,6 +5492,7 @@ var CacheStorageRepository = class {
       options: {
         cacheName: config.options?.cacheName ?? CACHE_NAME,
         ttl: config.options?.ttl ?? 7 * 24 * 60 * 60 * 1e3,
+        // 7 days default
         ...config.options
       }
     };
@@ -5301,9 +5500,17 @@ var CacheStorageRepository = class {
     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);
@@ -5327,6 +5534,9 @@ var CacheStorageRepository = class {
       throw new TranslationNotFoundError(key);
     }
   }
+  /**
+   * Set a translation value
+   */
   async set(key, value) {
     if (!this.available) return;
     try {
@@ -5345,6 +5555,9 @@ var CacheStorageRepository = class {
     } catch {
     }
   }
+  /**
+   * Remove a translation by key
+   */
   async remove(key) {
     if (!this.available) return;
     try {
@@ -5353,6 +5566,9 @@ var CacheStorageRepository = class {
     } catch {
     }
   }
+  /**
+   * Clear all LionRapid entries from the cache
+   */
   async clear() {
     if (!this.available) return;
     try {
@@ -5364,6 +5580,9 @@ var CacheStorageRepository = class {
     } catch {
     }
   }
+  /**
+   * Clear all entries for a specific namespace
+   */
   async clearNamespace(locale, namespace) {
     if (!this.available) return;
     const namespaceCacheKey = `@${locale}:${namespace}`;
@@ -5381,6 +5600,10 @@ var CacheStorageRepository = class {
     } 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);
@@ -5391,16 +5614,29 @@ var CacheStorageRepository = class {
       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;
@@ -5423,6 +5659,9 @@ var CacheStorageRepository = class {
     }
     return entries;
   }
+  /**
+   * Get cache statistics
+   */
   async getCacheStats() {
     if (!this.available) {
       return { size: 0, cacheName: this.cacheName };