@helpai/elements 0.5.0 → 0.7.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) {
@@ -2180,6 +2233,12 @@ var FeedbackBus = class {
   }
 };
 
+// src/ui/error-message.ts
+function errorMessageFor(error, strings) {
+  if (error instanceof StreamError && error.status === 429) return strings.errorRateLimited;
+  return strings.errorGeneric;
+}
+
 // src/ui/launcher.tsx
 import { useEffect, useState } from "preact/hooks";
 
@@ -4596,6 +4655,7 @@ function ArticleRow({ article, nav }) {
 function HelpRoot({ transport, strings, config, nav, panelProps }) {
   const tags = config.contentTags;
   const [state, setState] = useState6("loading");
+  const [errorMsg, setErrorMsg] = useState6(strings.errorGeneric);
   const [items, setItems] = useState6([]);
   const [query, setQuery] = useState6("");
   const [reloadKey, setReloadKey] = useState6(0);
@@ -4609,6 +4669,7 @@ function HelpRoot({ transport, strings, config, nav, panelProps }) {
     }).catch((err) => {
       if (cancelled) return;
       log12.warn("listContent (help) failed", { err });
+      setErrorMsg(errorMessageFor(err, strings));
       setState("error");
     });
     return () => {
@@ -4623,15 +4684,7 @@ function HelpRoot({ transport, strings, config, nav, panelProps }) {
     }
     if (state === "loading") return /* @__PURE__ */ jsx25(ModuleState, { message: strings.helpLoading, strings });
     if (state === "error") {
-      return /* @__PURE__ */ jsx25(
-        ModuleState,
-        {
-          tone: "error",
-          message: strings.errorGeneric,
-          onRetry: () => setReloadKey((k) => k + 1),
-          strings
-        }
-      );
+      return /* @__PURE__ */ jsx25(ModuleState, { tone: "error", message: errorMsg, onRetry: () => setReloadKey((k) => k + 1), strings });
     }
     if (items.length === 0) return /* @__PURE__ */ jsx25(ModuleState, { message: strings.helpEmpty, strings });
     return groupByCategory(items).map(([category, rows]) => /* @__PURE__ */ jsxs20("section", { class: `${p18}-help-group`, children: [
@@ -4781,6 +4834,7 @@ var log14 = logger.scope("news");
 function NewsRoot({ transport, strings, config, nav, panelProps }) {
   const tags = config.contentTags;
   const [state, setState] = useState8("loading");
+  const [errorMsg, setErrorMsg] = useState8(strings.errorGeneric);
   const [items, setItems] = useState8([]);
   const [reloadKey, setReloadKey] = useState8(0);
   useEffect13(() => {
@@ -4793,6 +4847,7 @@ function NewsRoot({ transport, strings, config, nav, panelProps }) {
     }).catch((err) => {
       if (cancelled) return;
       log14.warn("listContent (news) failed", { err });
+      setErrorMsg(errorMessageFor(err, strings));
       setState("error");
     });
     return () => {
@@ -4802,15 +4857,7 @@ function NewsRoot({ transport, strings, config, nav, panelProps }) {
   function renderBody() {
     if (state === "loading") return /* @__PURE__ */ jsx28(ModuleState, { message: strings.newsLoading, strings });
     if (state === "error") {
-      return /* @__PURE__ */ jsx28(
-        ModuleState,
-        {
-          tone: "error",
-          message: strings.errorGeneric,
-          onRetry: () => setReloadKey((k) => k + 1),
-          strings
-        }
-      );
+      return /* @__PURE__ */ jsx28(ModuleState, { tone: "error", message: errorMsg, onRetry: () => setReloadKey((k) => k + 1), strings });
     }
     if (items.length === 0) return /* @__PURE__ */ jsx28(ModuleState, { message: strings.newsEmpty, strings });
     return /* @__PURE__ */ jsx28("div", { class: `${p21}-news-list`, children: items.map((item) => /* @__PURE__ */ jsxs22(
@@ -5517,7 +5564,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 = errorMessageFor(error, options.strings);
         feedback.play("error");
         bus.emit("error", error);
         options.onError?.(error);