@helpai/elements 0.5.0 → 0.6.0

package/index.d.ts

@@ -40,7 +40,7 @@ interface ClientStorage {
  * populated {@link Strings} map. UI components then read `strings.send` as a
  * normal property access — no per-render lookup, no per-render allocation.
  */
-type StringKey = "launcherOpen" | "panelTitle" | "composerPlaceholder" | "send" | "stop" | "attach" | "micStart" | "micStop" | "micUnsupported" | "expand" | "collapse" | "fullscreen" | "exitFullscreen" | "resizeHandle" | "popOut" | "close" | "moreActions" | "soundOn" | "soundOff" | "language" | "theme" | "themeAuto" | "themeLight" | "themeDark" | "history" | "historyTitle" | "historyEmpty" | "historyLoading" | "historyNewChat" | "historyBack" | "messagesLoading" | "chatClosed" | "startNewConversation" | "dateToday" | "dateYesterday" | "dateLastWeek" | "dateOlder" | "newConversation" | "dropZone" | "attachmentTooLarge" | "attachmentTooMany" | "attachmentMimeRejected" | "errorRetry" | "errorGeneric" | "loading" | "thinking" | "thoughts" | "usedTool" | "collapseSidebar" | "expandSidebar" | "tabHome" | "tabMessages" | "tabHelp" | "tabNews" | "modulesEmpty" | "moduleBack" | "contentLoading" | "homeGreeting" | "homeGreetingNamed" | "homeGreetingLead" | "homeSearchPlaceholder" | "homeContentTitle" | "helpTitle" | "helpSearchPlaceholder" | "helpEmpty" | "helpLoading" | "helpSearchEmpty" | "newsTitle" | "newsEmpty" | "newsLoading" | "newsBack" | "newsPublishedAt";
+type StringKey = "launcherOpen" | "panelTitle" | "composerPlaceholder" | "send" | "stop" | "attach" | "micStart" | "micStop" | "micUnsupported" | "expand" | "collapse" | "fullscreen" | "exitFullscreen" | "resizeHandle" | "popOut" | "close" | "moreActions" | "soundOn" | "soundOff" | "language" | "theme" | "themeAuto" | "themeLight" | "themeDark" | "history" | "historyTitle" | "historyEmpty" | "historyLoading" | "historyNewChat" | "historyBack" | "messagesLoading" | "chatClosed" | "startNewConversation" | "dateToday" | "dateYesterday" | "dateLastWeek" | "dateOlder" | "newConversation" | "dropZone" | "attachmentTooLarge" | "attachmentTooMany" | "attachmentMimeRejected" | "errorRetry" | "errorGeneric" | "errorRateLimited" | "loading" | "thinking" | "thoughts" | "usedTool" | "collapseSidebar" | "expandSidebar" | "tabHome" | "tabMessages" | "tabHelp" | "tabNews" | "modulesEmpty" | "moduleBack" | "contentLoading" | "homeGreeting" | "homeGreetingNamed" | "homeGreetingLead" | "homeSearchPlaceholder" | "homeContentTitle" | "helpTitle" | "helpSearchPlaceholder" | "helpEmpty" | "helpLoading" | "helpSearchEmpty" | "newsTitle" | "newsEmpty" | "newsLoading" | "newsBack" | "newsPublishedAt";
 /** A partial map for one locale — what overrides look like on the wire. */
 type LocaleStrings = Partial<Record<StringKey, string>>;
 /**

package/index.mjs

@@ -46,6 +46,7 @@ var STRINGS_EN = {
   dateYesterday: "Yesterday",
   dropZone: "Drop files to attach",
   errorGeneric: "Something went wrong",
+  errorRateLimited: "Too many requests \u2014 please try again in a moment.",
   errorRetry: "Retry",
   expand: "Expand",
   expandSidebar: "Expand sidebar",
@@ -936,9 +937,10 @@ function fillRandom(view) {
 
 // src/stream/types.ts
 var StreamError = class extends Error {
-  constructor(message, code, cause) {
+  constructor(message, code, status, cause) {
     super(message);
     __publicField(this, "code", code);
+    __publicField(this, "status", status);
     __publicField(this, "cause", cause);
     this.name = "StreamError";
   }
@@ -949,7 +951,7 @@ var log3 = logger.scope("parser");
 async function* parseChatStream(response, signal6) {
   if (!response.ok) {
     const text = await response.text().catch(() => "");
-    throw new StreamError(`server responded ${response.status}: ${text.slice(0, 200)}`, "server");
+    throw new StreamError(`server responded ${response.status}: ${text.slice(0, 200)}`, "server", response.status);
   }
   if (!response.body) throw new StreamError("response has no body", "no-body");
   const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
@@ -1113,15 +1115,27 @@ function messageToWireParts(m) {
 var log4 = logger.scope("transport");
 var MAX_RESUME_ATTEMPTS = 3;
 var RESUME_BACKOFF_MS = 400;
+var MAX_REQUEST_RETRIES = 3;
+var RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 425, 429, 500, 502, 503, 504]);
+function backoffMs(attempt) {
+  return RESUME_BACKOFF_MS * 2 ** attempt + Math.floor(Math.random() * 250);
+}
+function retryAfterMs(headers) {
+  const raw = headers.get("retry-after");
+  if (!raw) return null;
+  const secs = Number(raw);
+  const ms = Number.isFinite(secs) ? secs * 1e3 : Date.parse(raw) - Date.now();
+  return Number.isFinite(ms) && ms >= 0 ? Math.min(ms, 3e4) : null;
+}
 function sleep(ms, signal6) {
   return new Promise((resolve) => {
-    if (signal6.aborted) return resolve();
+    if (signal6?.aborted) return resolve();
     const id = setTimeout(done, ms);
     const onAbort = () => done();
-    signal6.addEventListener("abort", onAbort, { once: true });
+    signal6?.addEventListener("abort", onAbort, { once: true });
     function done() {
       clearTimeout(id);
-      signal6.removeEventListener("abort", onAbort);
+      signal6?.removeEventListener("abort", onAbort);
       resolve();
     }
   });
@@ -1375,6 +1389,7 @@ var AgentTransport = class {
       }
     } catch (err) {
       if (ctrl.signal.aborted) return true;
+      if (err instanceof StreamError && err.status !== void 0) throw err;
       log4.debug("stream segment dropped", { err });
     }
     return false;
@@ -1419,13 +1434,23 @@ var AgentTransport = class {
     url.searchParams.set("resumeAt", String(resumeAt));
     return url.toString();
   }
+  // JSON requests are idempotent (reads, or full-snapshot writes like
+  // update-settings / mark-read / start-session), so they auto-retry transient
+  // failures. The message POST is NOT in here — re-sending could duplicate the
+  // reply, so it surfaces an error for the user to retry (see `openMessageStream`).
   async postJson(path, body, label) {
-    const res = await this.fetchImpl(this.url(path), {
-      method: "POST",
-      credentials: "omit",
-      headers: { "content-type": "application/json", ...this.opts.auth.headers() },
-      body: JSON.stringify(this.withEnvelope(body))
-    });
+    const res = await this.fetchWithRetry(
+      () => [
+        this.url(path),
+        {
+          method: "POST",
+          credentials: "omit",
+          headers: { "content-type": "application/json", ...this.opts.auth.headers() },
+          body: JSON.stringify(this.withEnvelope(body))
+        }
+      ],
+      label
+    );
     return this.assertOk(res, label);
   }
   async postForm(path, body, label) {
@@ -1438,16 +1463,44 @@ var AgentTransport = class {
     return this.assertOk(res, label);
   }
   async getJson(urlOrPath, label) {
-    const res = await this.fetchImpl(this.withEnvelopeQuery(urlOrPath), {
-      method: "GET",
-      credentials: "omit",
-      headers: { accept: "application/json", ...this.opts.auth.headers() }
-    });
+    const res = await this.fetchWithRetry(
+      () => [
+        this.withEnvelopeQuery(urlOrPath),
+        { method: "GET", credentials: "omit", headers: { accept: "application/json", ...this.opts.auth.headers() } }
+      ],
+      label
+    );
     return this.assertOk(res, label);
   }
-  /** Throw on non-2xx, otherwise return the parsed JSON body. */
+  /**
+   * Fetch with bounded retries for *transient* failures: retryable statuses
+   * (429 / 5xx / …) and network errors, honoring `Retry-After` (else backoff +
+   * jitter). Terminal statuses (4xx) return immediately for the caller to throw.
+   * Use only for idempotent requests.
+   */
+  async fetchWithRetry(build, label) {
+    for (let attempt = 0; ; attempt++) {
+      const [reqUrl, init2] = build();
+      let res;
+      try {
+        res = await this.fetchImpl(reqUrl, init2);
+      } catch (err) {
+        if (attempt >= MAX_REQUEST_RETRIES) {
+          throw new StreamError(`${label} failed: network error`, "network", void 0, err);
+        }
+        log4.debug("request network error \u2014 retrying", { label, attempt });
+        await sleep(backoffMs(attempt));
+        continue;
+      }
+      if (res.ok || !RETRYABLE_STATUS.has(res.status) || attempt >= MAX_REQUEST_RETRIES) return res;
+      const wait = retryAfterMs(res.headers) ?? backoffMs(attempt);
+      log4.debug("request retryable status \u2014 retrying", { label, status: res.status, attempt, wait });
+      await sleep(wait);
+    }
+  }
+  /** Throw on non-2xx (with the status attached), otherwise parse the JSON body. */
   async assertOk(res, label) {
-    if (!res.ok) throw new StreamError(`${label} failed: ${res.status}`, "server");
+    if (!res.ok) throw new StreamError(`${label} failed: ${res.status}`, "server", res.status);
     return await res.json();
   }
   url(pathOrUrl) {
@@ -5453,7 +5506,7 @@ function App({ options, hostElement, bus }) {
         emitMessage(bus, options, "assistant", assistantText(assistantMsg));
       } catch (error) {
         assistantMsg.status = "error";
-        assistantMsg.errorText = error instanceof Error ? error.message : "Unknown error";
+        assistantMsg.errorText = error instanceof StreamError && error.status === 429 ? options.strings.errorRateLimited : options.strings.errorGeneric;
         feedback.play("error");
         bus.emit("error", error);
         options.onError?.(error);

package/package.json

@@ -80,5 +80,5 @@
   ],
   "type": "module",
   "types": "./index.d.ts",
-  "version": "0.5.0"
+  "version": "0.6.0"
 }

package/web-component.mjs

@@ -46,6 +46,7 @@ var STRINGS_EN = {
   dateYesterday: "Yesterday",
   dropZone: "Drop files to attach",
   errorGeneric: "Something went wrong",
+  errorRateLimited: "Too many requests \u2014 please try again in a moment.",
   errorRetry: "Retry",
   expand: "Expand",
   expandSidebar: "Expand sidebar",
@@ -1000,9 +1001,10 @@ function fillRandom(view) {
 
 // src/stream/types.ts
 var StreamError = class extends Error {
-  constructor(message, code, cause) {
+  constructor(message, code, status, cause) {
     super(message);
     __publicField(this, "code", code);
+    __publicField(this, "status", status);
     __publicField(this, "cause", cause);
     this.name = "StreamError";
   }
@@ -1013,7 +1015,7 @@ var log3 = logger.scope("parser");
 async function* parseChatStream(response, signal6) {
   if (!response.ok) {
     const text = await response.text().catch(() => "");
-    throw new StreamError(`server responded ${response.status}: ${text.slice(0, 200)}`, "server");
+    throw new StreamError(`server responded ${response.status}: ${text.slice(0, 200)}`, "server", response.status);
   }
   if (!response.body) throw new StreamError("response has no body", "no-body");
   const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
@@ -1177,15 +1179,27 @@ function messageToWireParts(m) {
 var log4 = logger.scope("transport");
 var MAX_RESUME_ATTEMPTS = 3;
 var RESUME_BACKOFF_MS = 400;
+var MAX_REQUEST_RETRIES = 3;
+var RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 425, 429, 500, 502, 503, 504]);
+function backoffMs(attempt) {
+  return RESUME_BACKOFF_MS * 2 ** attempt + Math.floor(Math.random() * 250);
+}
+function retryAfterMs(headers) {
+  const raw = headers.get("retry-after");
+  if (!raw) return null;
+  const secs = Number(raw);
+  const ms = Number.isFinite(secs) ? secs * 1e3 : Date.parse(raw) - Date.now();
+  return Number.isFinite(ms) && ms >= 0 ? Math.min(ms, 3e4) : null;
+}
 function sleep(ms, signal6) {
   return new Promise((resolve) => {
-    if (signal6.aborted) return resolve();
+    if (signal6?.aborted) return resolve();
     const id = setTimeout(done, ms);
     const onAbort = () => done();
-    signal6.addEventListener("abort", onAbort, { once: true });
+    signal6?.addEventListener("abort", onAbort, { once: true });
     function done() {
       clearTimeout(id);
-      signal6.removeEventListener("abort", onAbort);
+      signal6?.removeEventListener("abort", onAbort);
       resolve();
     }
   });
@@ -1439,6 +1453,7 @@ var AgentTransport = class {
       }
     } catch (err) {
       if (ctrl.signal.aborted) return true;
+      if (err instanceof StreamError && err.status !== void 0) throw err;
       log4.debug("stream segment dropped", { err });
     }
     return false;
@@ -1483,13 +1498,23 @@ var AgentTransport = class {
     url.searchParams.set("resumeAt", String(resumeAt));
     return url.toString();
   }
+  // JSON requests are idempotent (reads, or full-snapshot writes like
+  // update-settings / mark-read / start-session), so they auto-retry transient
+  // failures. The message POST is NOT in here — re-sending could duplicate the
+  // reply, so it surfaces an error for the user to retry (see `openMessageStream`).
   async postJson(path, body, label) {
-    const res = await this.fetchImpl(this.url(path), {
-      method: "POST",
-      credentials: "omit",
-      headers: { "content-type": "application/json", ...this.opts.auth.headers() },
-      body: JSON.stringify(this.withEnvelope(body))
-    });
+    const res = await this.fetchWithRetry(
+      () => [
+        this.url(path),
+        {
+          method: "POST",
+          credentials: "omit",
+          headers: { "content-type": "application/json", ...this.opts.auth.headers() },
+          body: JSON.stringify(this.withEnvelope(body))
+        }
+      ],
+      label
+    );
     return this.assertOk(res, label);
   }
   async postForm(path, body, label) {
@@ -1502,16 +1527,44 @@ var AgentTransport = class {
     return this.assertOk(res, label);
   }
   async getJson(urlOrPath, label) {
-    const res = await this.fetchImpl(this.withEnvelopeQuery(urlOrPath), {
-      method: "GET",
-      credentials: "omit",
-      headers: { accept: "application/json", ...this.opts.auth.headers() }
-    });
+    const res = await this.fetchWithRetry(
+      () => [
+        this.withEnvelopeQuery(urlOrPath),
+        { method: "GET", credentials: "omit", headers: { accept: "application/json", ...this.opts.auth.headers() } }
+      ],
+      label
+    );
     return this.assertOk(res, label);
   }
-  /** Throw on non-2xx, otherwise return the parsed JSON body. */
+  /**
+   * Fetch with bounded retries for *transient* failures: retryable statuses
+   * (429 / 5xx / …) and network errors, honoring `Retry-After` (else backoff +
+   * jitter). Terminal statuses (4xx) return immediately for the caller to throw.
+   * Use only for idempotent requests.
+   */
+  async fetchWithRetry(build, label) {
+    for (let attempt = 0; ; attempt++) {
+      const [reqUrl, init] = build();
+      let res;
+      try {
+        res = await this.fetchImpl(reqUrl, init);
+      } catch (err) {
+        if (attempt >= MAX_REQUEST_RETRIES) {
+          throw new StreamError(`${label} failed: network error`, "network", void 0, err);
+        }
+        log4.debug("request network error \u2014 retrying", { label, attempt });
+        await sleep(backoffMs(attempt));
+        continue;
+      }
+      if (res.ok || !RETRYABLE_STATUS.has(res.status) || attempt >= MAX_REQUEST_RETRIES) return res;
+      const wait = retryAfterMs(res.headers) ?? backoffMs(attempt);
+      log4.debug("request retryable status \u2014 retrying", { label, status: res.status, attempt, wait });
+      await sleep(wait);
+    }
+  }
+  /** Throw on non-2xx (with the status attached), otherwise parse the JSON body. */
   async assertOk(res, label) {
-    if (!res.ok) throw new StreamError(`${label} failed: ${res.status}`, "server");
+    if (!res.ok) throw new StreamError(`${label} failed: ${res.status}`, "server", res.status);
     return await res.json();
   }
   url(pathOrUrl) {
@@ -5517,7 +5570,7 @@ function App({ options, hostElement, bus }) {
         emitMessage(bus, options, "assistant", assistantText(assistantMsg));
       } catch (error) {
         assistantMsg.status = "error";
-        assistantMsg.errorText = error instanceof Error ? error.message : "Unknown error";
+        assistantMsg.errorText = error instanceof StreamError && error.status === 429 ? options.strings.errorRateLimited : options.strings.errorGeneric;
         feedback.play("error");
         bus.emit("error", error);
         options.onError?.(error);