npm - @frockbot/client-core - Versions diffs - 0.3.11 → 0.3.12 - Mend

@frockbot/client-core 0.3.11 → 0.3.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/client-core",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "private": false,
   "type": "module",
   "exports": {
@@ -13,10 +13,10 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/configuration-core": "0.3.11",
-    "@frockbot/connection-core": "0.3.11",
-    "@frockbot/kernel-contracts": "0.3.11",
-    "@frockbot/protocol": "0.3.11",
+    "@frockbot/configuration-core": "0.3.12",
+    "@frockbot/connection-core": "0.3.12",
+    "@frockbot/kernel-contracts": "0.3.12",
+    "@frockbot/protocol": "0.3.12",
     "vue": "3.5.41"
   },
   "devDependencies": {

package/src/errors.test.ts ADDED Viewed

@@ -0,0 +1,142 @@
+import { describe, expect, test } from "bun:test";
+import {
+  classifyClientFailureV1,
+  clientFailureDetailV1,
+  presentClientFailureV1,
+  readJsonResponseV1,
+  serverRefusalMessageV1,
+  TransportFailureV1,
+} from "./errors.js";
+describe("readJsonResponseV1", () => {
+  test("returns the parsed body of a good response", async () => {
+    const response = new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+    });
+    expect(await readJsonResponseV1(response)).toEqual({ ok: true });
+  });
+  test("an HTML error body is a transport failure, not a parse error", async () => {
+    // Incident 1: the visible symptom was `Unexpected token '<'` in the
+    // sidebar.
+    const response = new Response("<html><body>Bad gateway</body></html>", {
+      status: 502,
+      headers: { "content-type": "text/html" },
+    });
+    const failure = await readJsonResponseV1(response).catch(
+      (error: unknown) => error,
+    );
+    expect(failure).toBeInstanceOf(TransportFailureV1);
+    const transport = failure as TransportFailureV1;
+    expect(transport.kind).toBe("unreachable");
+    expect(transport.message).not.toContain("JSON");
+    expect(transport.message).toBe("Couldn't reach FrockBot.");
+    expect(transport.detail).toContain("Bad gateway");
+  });
+  test("a 200 with a non-JSON body is unreachable rather than a crash", async () => {
+    const response = new Response("<html>proxy</html>", { status: 200 });
+    const failure = (await readJsonResponseV1(response).catch(
+      (error: unknown) => error,
+    )) as TransportFailureV1;
+    expect(failure.kind).toBe("unreachable");
+  });
+  test("a refusal's own sentence is offered, a fault's is not", async () => {
+    // A 4xx is the deployment explaining a rule it holds, in words it wrote
+    // for a person; a 5xx is a fault, and its text is about plumbing.
+    const refusal = (await readJsonResponseV1(
+      new Response(
+        JSON.stringify({ error: "Your message is too long. Keep it short." }),
+        { status: 413 },
+      ),
+    ).catch((error: unknown) => error)) as TransportFailureV1;
+    expect(serverRefusalMessageV1(refusal)).toBe(
+      "Your message is too long. Keep it short.",
+    );
+    const fault = (await readJsonResponseV1(
+      new Response(JSON.stringify({ error: "R2 is down" }), { status: 500 }),
+    ).catch((error: unknown) => error)) as TransportFailureV1;
+    expect(serverRefusalMessageV1(fault)).toBeUndefined();
+    expect(fault.detail).toBe("R2 is down");
+    // Nothing written, nothing to offer.
+    const bare = (await readJsonResponseV1(
+      new Response("{}", { status: 400 }),
+    ).catch((error: unknown) => error)) as TransportFailureV1;
+    expect(serverRefusalMessageV1(bare)).toBeUndefined();
+    expect(serverRefusalMessageV1(new Error("boom"))).toBeUndefined();
+  });
+  test("the server's error field is kept as detail, not as the message", async () => {
+    const response = new Response(JSON.stringify({ error: "boom" }), {
+      status: 500,
+    });
+    const failure = (await readJsonResponseV1(response).catch(
+      (error: unknown) => error,
+    )) as TransportFailureV1;
+    expect(failure.kind).toBe("server");
+    expect(failure.detail).toBe("boom");
+    expect(failure.message).not.toBe("boom");
+  });
+  test("carries the definitive flag through", async () => {
+    const response = new Response(
+      JSON.stringify({ error: "no", definitive: true }),
+      { status: 400 },
+    );
+    const failure = (await readJsonResponseV1(response).catch(
+      (error: unknown) => error,
+    )) as TransportFailureV1;
+    expect(failure.definitive).toBe(true);
+    expect(failure.kind).toBe("rejected");
+  });
+  test("classifies by status", async () => {
+    const kindOf = async (status: number): Promise<string> => {
+      const failure = (await readJsonResponseV1(
+        new Response("{}", { status }),
+      ).catch((error: unknown) => error)) as TransportFailureV1;
+      return failure.kind;
+    };
+    expect(await kindOf(401)).toBe("denied");
+    expect(await kindOf(403)).toBe("denied");
+    expect(await kindOf(404)).toBe("missing");
+    expect(await kindOf(500)).toBe("server");
+    expect(await kindOf(503)).toBe("unreachable");
+    expect(await kindOf(422)).toBe("rejected");
+  });
+});
+describe("presentClientFailureV1", () => {
+  test("names what the User was doing", () => {
+    const failure = new TransportFailureV1({
+      kind: "server",
+      detail: "boom",
+    });
+    expect(presentClientFailureV1(failure, "load your plugins")).toBe(
+      "Couldn't load your plugins. Something went wrong at our end.",
+    );
+  });
+  test("never repeats a parse error", () => {
+    const parse = new SyntaxError(
+      `Unexpected token '<', "<html><bod"... is not valid JSON`,
+    );
+    const sentence = presentClientFailureV1(parse, "load your flock");
+    expect(sentence).not.toContain("JSON");
+    expect(sentence).toBe("Couldn't load your flock — FrockBot didn't answer.");
+  });
+  test("a dropped fetch reads as unreachable", () => {
+    expect(presentClientFailureV1(new TypeError("Failed to fetch"))).toBe(
+      "Couldn't reach FrockBot.",
+    );
+  });
+  test("keeps the raw text available for the console", () => {
+    expect(clientFailureDetailV1(new Error("boom"))).toBe("boom");
+    expect(classifyClientFailureV1("boom").detail).toBe("boom");
+  });
+});

package/src/errors.ts ADDED Viewed

@@ -0,0 +1,242 @@
+/*
+ * The client's one boundary between a failed request and a sentence a person
+ * reads.
+ *
+ * Two habits produced the failures this module exists to stop. The first was
+ * calling `response.json()` before looking at the response: a 502 whose body is
+ * an HTML error page then fails inside `JSON.parse`, and what reached the
+ * screen was `Unexpected token '<'` — a message about this client's own
+ * parsing, in a place the User was told about their Bots. The second was
+ * putting the server's `error` field on screen verbatim: a 500 whose body was
+ * `{"error":"boom"}` rendered as the single red word `boom`.
+ *
+ * So: `readJsonResponseV1` is the only way a response becomes a value, and it
+ * throws `TransportFailureV1` with the raw text kept out of the message;
+ * `presentClientFailureV1` is the only way a caught error becomes text on a
+ * surface. Callers pass what the User was trying to do — "load your plugins" —
+ * and get one short sentence back. The raw detail stays on the error for the
+ * console.
+ */
+/** What went wrong, at the coarseness a sentence can be written from. */
+export type ClientFailureKindV1 =
+  "offline" | "unreachable" | "server" | "denied" | "missing" | "rejected";
+export interface ClientFailureV1 {
+  readonly kind: ClientFailureKindV1;
+  readonly status?: number;
+  /** The raw text — for the console and for tests, never for the screen. */
+  readonly detail: string;
+  /**
+   * The sentence the deployment wrote for a person, when it wrote one: the
+   * `error` field of a refusal it decided on, like "Your message is too long."
+   * A refusal is the product explaining a rule it holds, so that sentence is
+   * the User's to read — unlike a fault's text, which is about plumbing. Only
+   * set for a 4xx, and only when the body actually carried one.
+   */
+  readonly serverMessage?: string;
+}
+/** A request that did not produce a usable JSON body. */
+export class TransportFailureV1 extends Error implements ClientFailureV1 {
+  readonly kind: ClientFailureKindV1;
+  readonly status?: number;
+  readonly detail: string;
+  readonly serverMessage?: string;
+  /**
+   * The server said this outcome is final, so a caller that retries pending
+   * work must stop rather than try again. Carried through because the flock's
+   * pending-create replay depends on it.
+   */
+  readonly definitive?: boolean;
+  constructor(failure: ClientFailureV1 & { definitive?: boolean }) {
+    // The message is the presentable sentence, so an error that escapes to a
+    // `catch` that only reads `.message` still says something sane.
+    super(presentClientFailureV1Kind(failure.kind));
+    this.name = "TransportFailureV1";
+    this.kind = failure.kind;
+    if (failure.status !== undefined) this.status = failure.status;
+    this.detail = failure.detail;
+    if (failure.serverMessage !== undefined) {
+      this.serverMessage = failure.serverMessage;
+    }
+    if (failure.definitive !== undefined) this.definitive = failure.definitive;
+  }
+}
+function kindForStatusV1(status: number): ClientFailureKindV1 {
+  if (status === 401 || status === 403) return "denied";
+  if (status === 404 || status === 410) return "missing";
+  if (status === 408 || status === 429) return "unreachable";
+  if (status === 502 || status === 503 || status === 504) return "unreachable";
+  if (status >= 500) return "server";
+  return "rejected";
+}
+function serverErrorStringV1(value: unknown): string | undefined {
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    "error" in value &&
+    typeof (value as { error: unknown }).error === "string"
+  ) {
+    const written = (value as { error: string }).error.trim();
+    return written === "" ? undefined : written;
+  }
+  return undefined;
+}
+function isDefinitiveV1(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "definitive" in value &&
+    (value as { definitive: unknown }).definitive === true
+  );
+}
+/**
+ * Read a response as JSON, or throw a failure that can be presented.
+ *
+ * The body is taken as text first so a non-JSON body is a *classified*
+ * failure rather than a `SyntaxError` about this client's parser.
+ */
+export async function readJsonResponseV1(response: Response): Promise<unknown> {
+  const body = await response.text().catch(() => "");
+  let parsed: unknown;
+  let readable = true;
+  try {
+    parsed = body.trim() === "" ? undefined : (JSON.parse(body) as unknown);
+  } catch {
+    readable = false;
+  }
+  if (!response.ok) {
+    const written = readable ? serverErrorStringV1(parsed) : undefined;
+    throw new TransportFailureV1({
+      kind: kindForStatusV1(response.status),
+      status: response.status,
+      detail:
+        written ??
+        (readable
+          ? `HTTP ${response.status}`
+          : `HTTP ${response.status}: ${body.slice(0, 200)}`),
+      // A refusal the deployment decided on, in words it chose for a person.
+      // A fault's text is never that, whatever it happens to say.
+      ...(written !== undefined && response.status < 500
+        ? { serverMessage: written }
+        : {}),
+      ...(readable && isDefinitiveV1(parsed) ? { definitive: true } : {}),
+    });
+  }
+  if (!readable) {
+    // A 200 that is not JSON is something between this client and the
+    // deployment answering — a proxy page, a captive portal, a stale worker.
+    throw new TransportFailureV1({
+      kind: "unreachable",
+      status: response.status,
+      detail: `Response body was not JSON: ${body.slice(0, 200)}`,
+    });
+  }
+  return parsed;
+}
+/** What a caught value amounts to, whatever threw it. */
+export function classifyClientFailureV1(error: unknown): ClientFailureV1 {
+  if (error instanceof TransportFailureV1) return error;
+  const detail =
+    error instanceof Error ? error.message : String(error ?? "unknown error");
+  /*
+   * A transport that is not this one may still have read a status and put it
+   * on the error — the desktop bridge does, and so does anything that decodes
+   * a refusal before throwing. A 4xx there means the same thing it means here:
+   * the deployment read the request, refused it, and said why in words meant
+   * for a person.
+   */
+  const status =
+    typeof error === "object" &&
+    error !== null &&
+    "status" in error &&
+    typeof (error as { status: unknown }).status === "number"
+      ? (error as { status: number }).status
+      : undefined;
+  if (status !== undefined && status >= 400) {
+    return {
+      kind: kindForStatusV1(status),
+      status,
+      detail,
+      ...(status < 500 && detail !== "" ? { serverMessage: detail } : {}),
+    };
+  }
+  // `fetch` rejects with a TypeError when the request never left, or never
+  // came back. The browser's own offline flag is the only way to tell the two
+  // apart, and it is advisory, so it only picks the wording.
+  const offline =
+    typeof navigator !== "undefined" && navigator.onLine === false;
+  if (error instanceof TypeError) {
+    return { kind: offline ? "offline" : "unreachable", detail };
+  }
+  if (/JSON|Unexpected token/i.test(detail)) {
+    return { kind: "unreachable", detail };
+  }
+  return { kind: offline ? "offline" : "rejected", detail };
+}
+function presentClientFailureV1Kind(
+  kind: ClientFailureKindV1,
+  action?: string,
+): string {
+  const doing = action ? ` ${action}` : "";
+  switch (kind) {
+    case "offline":
+      return "You're offline. Reconnect and try again.";
+    case "unreachable":
+      return action
+        ? `Couldn't${doing} — FrockBot didn't answer.`
+        : "Couldn't reach FrockBot.";
+    case "server":
+      return action
+        ? `Couldn't${doing}. Something went wrong at our end.`
+        : "Something went wrong at our end.";
+    case "denied":
+      return "You're not signed in any more. Sign in again.";
+    case "missing":
+      return action
+        ? `Couldn't${doing} — it isn't there.`
+        : "That isn't there.";
+    case "rejected":
+      return action ? `Couldn't${doing}.` : "That didn't work.";
+  }
+}
+/**
+ * One short sentence for a failed request.
+ *
+ * `action` is what the User was doing, as a verb phrase that reads after
+ * "Couldn't": `presentClientFailureV1(error, "load your plugins")`.
+ */
+export function presentClientFailureV1(
+  error: unknown,
+  action?: string,
+): string {
+  return presentClientFailureV1Kind(
+    classifyClientFailureV1(error).kind,
+    action,
+  );
+}
+/**
+ * The sentence the deployment wrote for a person, if it wrote one.
+ *
+ * Use it where a refusal's own reason is what the User needs — the send that
+ * was too long, the plugin that needs another turned on first — and fall back
+ * to `presentClientFailureV1`. A fault never carries one.
+ */
+export function serverRefusalMessageV1(error: unknown): string | undefined {
+  return classifyClientFailureV1(error).serverMessage;
+}
+/** The raw text, for a console line or a log — never for a surface. */
+export function clientFailureDetailV1(error: unknown): string {
+  return classifyClientFailureV1(error).detail;
+}

package/src/index.ts CHANGED Viewed

@@ -12,6 +12,17 @@ import { decodeExternalAuthorizationUrl } from "@frockbot/protocol";
 export { decodeExternalAuthorizationUrl };
+export {
+  classifyClientFailureV1,
+  clientFailureDetailV1,
+  presentClientFailureV1,
+  readJsonResponseV1,
+  serverRefusalMessageV1,
+  TransportFailureV1,
+  type ClientFailureKindV1,
+  type ClientFailureV1,
+} from "./errors.js";
 import type {
   ConfigurationCommandV1,
   ConfigurationQueryV1,
@@ -103,14 +114,21 @@ export type ClientStartConnectionResult = StartConnectionResult;
  * A durable Session event that belongs to no Turn — a rename, today. The chat
  * shows it as a system line rather than as a message from either party.
  */
-export interface ClientAnnouncement {
-  type: "bot/renamed";
-  announcementId: string;
-  at: string;
-  from: string;
-  to: string;
-  namedBy: "user" | "bot";
-}
+export type ClientAnnouncement =
+  | {
+      type: "bot/renamed";
+      announcementId: string;
+      at: string;
+      from: string;
+      to: string;
+      namedBy: "user" | "bot";
+    }
+  | {
+      type: "conversation/compacted";
+      announcementId: string;
+      at: string;
+      throughTurn: number;
+    };
 export interface ClientRun {
   runId: string;