@foldspace_npm/harness 0.1.11 → 0.1.12

package/src/runtime/http.ts

@@ -1,11 +1,11 @@
 // HTTP against the customer's own API, from inside their signed-in page.
 //
-// Lifted from the Transparency Catalog build. Errors are RETURNED, never
+// Lifted from a production build. Errors are RETURNED, never
 // thrown, and never carry the token or a raw API error body back to the agent.
 //
 // Two of three early builds used Authorization: Bearer from localStorage, not
 // cookies. Reach for credentials: "include" only when you have observed the
-// app doing that. Custom headers (Joist-style) belong in a tenant override of
+// app doing that. A custom-header scheme belongs in a tenant override of
 // apiFetch, not here.
 
 import { getConfig } from "./config";
@@ -103,9 +103,20 @@ export interface ApiSuccess<T> {
  * offline, connection refused). Timeouts set `unreachable: false` and
  * `error: "Request timed out."`. Empty `API_BASE` / `AUTH_SOURCE` also
  * return `{ ok: false }` with status 0 — they do not throw.
+ *
+ * Branch on `reason`, not on `status`: a search that finds nothing, an expired
+ * session and a throttled call are three different widget states, and
+ * `renderFailure` picks the right one for you.
  */
 export interface ApiFailure {
   ok: false;
+  /**
+   * Why it failed. Always set by the harness; optional only so a tenant's own
+   * `apiFetch` override keeps compiling.
+   */
+  reason?: FailureReason;
+  /** From `Retry-After` on a 429, when the API sent one. */
+  retryAfterMs?: number;
   /** HTTP status, or `0` when there was no response / config was missing. */
   status: number;
   /** Safe, user-facing sentence. Pass this to `renderError`. */
@@ -119,6 +130,28 @@ export interface ApiFailure {
   unreachable?: boolean;
 }
 
+/**
+ * Why a call failed, in terms a widget can act on.
+ *
+ * - `signed_out` — no token on the page, or the API answered 401. The session
+ *   observed at build time is not the session at run time; expect this.
+ * - `forbidden` — 403. Show the product's own limit; never reach for another token.
+ * - `not_found` — 404. **Not an error**: render it as an empty state.
+ * - `rate_limited` — 429. `retryAfterMs` is set when the API said how long.
+ * - `timeout` / `unreachable` — no usable response.
+ * - `config` — `API_BASE` / `AUTH_SOURCE` / public origin not set yet.
+ * - `server` — any other non-2xx.
+ */
+export type FailureReason =
+  | "signed_out"
+  | "forbidden"
+  | "not_found"
+  | "rate_limited"
+  | "timeout"
+  | "unreachable"
+  | "config"
+  | "server";
+
 /** Discriminated result of a customer-API call. Branch on `ok`. */
 export type ApiResult<T> = ApiSuccess<T> | ApiFailure;
 
@@ -128,6 +161,7 @@ function missingConfigResult(): ApiResult<never> | null {
     return {
       ok: false,
       status: 0,
+      reason: "config",
       error: "API_BASE is not set — capture the app's XHR first.",
     };
   }
@@ -135,6 +169,7 @@ function missingConfigResult(): ApiResult<never> | null {
     return {
       ok: false,
       status: 0,
+      reason: "config",
       error: "AUTH_SOURCE is not set — capture the app's session first.",
     };
   }
@@ -151,6 +186,62 @@ function failureDetail(parsed: unknown): string | undefined {
   return undefined;
 }
 
+function retryAfterMs(res: Response): number | undefined {
+  const raw = res.headers?.get?.("Retry-After");
+  if (!raw) return undefined;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+  const at = Date.parse(raw);
+  return Number.isNaN(at) ? undefined : Math.max(0, at - Date.now());
+}
+
+/**
+ * One mapping from HTTP status to a failure a widget can act on.
+ *
+ * Exported for a tenant's own `apiFetch` — an app that authenticates with a
+ * custom header or cookies replaces the transport, and should not also have to
+ * reinvent what a 401, a 404 or a 429 means. See recipes/swap-the-login-method.
+ */
+export function httpFailure(res: Response, fallback: string, detail?: string): ApiFailure {
+  const base = { ok: false as const, status: res.status, detail };
+  switch (res.status) {
+    case 401:
+      return { ...base, reason: "signed_out", error: "Your session expired. Sign in again." };
+    case 403:
+      return { ...base, reason: "forbidden", error: "You do not have access to that." };
+    case 404:
+      return { ...base, reason: "not_found", error: "That could not be found." };
+    case 429:
+      return {
+        ...base,
+        reason: "rate_limited",
+        retryAfterMs: retryAfterMs(res),
+        error: "Too many requests. Try again in a moment.",
+      };
+    default:
+      return { ...base, reason: "server", error: fallback };
+  }
+}
+
+/** The no-response half of {@link httpFailure}: a timeout, or a host that never answered. */
+export function networkFailure(error: unknown, timedOut: string, unreachable: string): ApiFailure {
+  const aborted = error instanceof Error && error.name === "AbortError";
+  return {
+    ok: false,
+    status: 0,
+    reason: aborted ? "timeout" : "unreachable",
+    unreachable: !aborted,
+    error: aborted ? timedOut : unreachable,
+  };
+}
+
+const SIGNED_OUT: ApiFailure = {
+  ok: false,
+  status: 401,
+  reason: "signed_out",
+  error: "Not signed in.",
+};
+
 /**
  * Authenticated JSON request against `apiBase` with `Authorization: Bearer`.
  *
@@ -174,7 +265,7 @@ export async function apiFetch<T = unknown>(
   if (missing) return missing;
 
   const token = getAuthToken();
-  if (!token) return { ok: false, status: 401, error: "Not signed in." };
+  if (!token) return SIGNED_OUT;
 
   const controller = new AbortController();
   const timer = setTimeout(
@@ -202,26 +293,12 @@ export async function apiFetch<T = unknown>(
     }
 
     if (!res.ok) {
-      return {
-        ok: false,
-        status: res.status,
-        error:
-          res.status === 401
-            ? "Your session expired. Sign in again."
-            : "That request could not be completed.",
-        detail: failureDetail(parsed),
-      };
+      return httpFailure(res, "That request could not be completed.", failureDetail(parsed));
     }
 
     return { ok: true, status: res.status, data: parsed as T };
   } catch (error) {
-    const aborted = error instanceof Error && error.name === "AbortError";
-    return {
-      ok: false,
-      status: 0,
-      unreachable: !aborted,
-      error: aborted ? "Request timed out." : "Could not reach the server.",
-    };
+    return networkFailure(error, "Request timed out.", "Could not reach the server.");
   } finally {
     clearTimeout(timer);
   }
@@ -275,7 +352,7 @@ export async function apiFetchBinary(
   if (missing) return missing;
 
   const token = getAuthToken();
-  if (!token) return { ok: false, status: 401, error: "Not signed in." };
+  if (!token) return SIGNED_OUT;
 
   const controller = new AbortController();
   const timer = setTimeout(
@@ -289,29 +366,14 @@ export async function apiFetchBinary(
       signal: controller.signal,
       headers: { Authorization: `Bearer ${token}`, ...(init.headers ?? {}) },
     });
-    if (!res.ok) {
-      return {
-        ok: false,
-        status: res.status,
-        error:
-          res.status === 401
-            ? "Your session expired. Sign in again."
-            : "That file could not be returned.",
-      };
-    }
+    if (!res.ok) return httpFailure(res, "That file could not be returned.");
     return {
       ok: true,
       status: res.status,
       data: new Uint8Array(await res.arrayBuffer()),
     };
   } catch (error) {
-    const aborted = error instanceof Error && error.name === "AbortError";
-    return {
-      ok: false,
-      status: 0,
-      unreachable: !aborted,
-      error: aborted ? "Download timed out." : "Could not reach the server.",
-    };
+    return networkFailure(error, "Download timed out.", "Could not reach the server.");
   } finally {
     clearTimeout(timer);
   }
@@ -321,8 +383,8 @@ export async function apiFetchBinary(
  * Unauthenticated JSON GET. No Bearer token.
  *
  * Origin is the second argument, or `RuntimeConfig.publicOrigin`. Path first
- * (Transparency Catalog calling convention). Use for marketing / public APIs,
- * not the signed-in product API.
+ * (the calling convention of the build it came from). Use for marketing /
+ * public APIs, not the signed-in product API.
  *
  * @param path - Path under the public origin
  * @param origin - Override `publicOrigin` for this call
@@ -338,6 +400,7 @@ export async function publicFetch<T = unknown>(
     return {
       ok: false,
       status: 0,
+      reason: "config",
       error: "No public origin is configured for this app.",
     };
   }
@@ -351,22 +414,10 @@ export async function publicFetch<T = unknown>(
       credentials: "include",
       signal: controller.signal,
     });
-    if (!res.ok) {
-      return {
-        ok: false,
-        status: res.status,
-        error: "That request could not be completed.",
-      };
-    }
+    if (!res.ok) return httpFailure(res, "That request could not be completed.");
     return { ok: true, status: res.status, data: (await res.json()) as T };
   } catch (error) {
-    const aborted = error instanceof Error && error.name === "AbortError";
-    return {
-      ok: false,
-      status: 0,
-      unreachable: !aborted,
-      error: aborted ? "The request timed out." : "Could not reach that host.",
-    };
+    return networkFailure(error, "The request timed out.", "Could not reach that host.");
   } finally {
     clearTimeout(timer);
   }

package/src/runtime/index.ts

@@ -21,8 +21,10 @@ export {
   apiFetchBinary,
   publicFetch,
   mapWithConcurrency,
+  httpFailure,
+  networkFailure,
 } from "./http";
-export type { ApiResult, ApiSuccess, ApiFailure } from "./http";
+export type { ApiResult, ApiSuccess, ApiFailure, FailureReason } from "./http";
 
 export { rankBy } from "./match";
 export type { FuzzyMatch, RankByOptions } from "./match";
@@ -32,5 +34,6 @@ export {
   renderEmpty,
   renderError,
   renderFatal,
+  renderFailure,
 } from "./render";
 export type { ViewHost } from "./render";

package/src/runtime/match.ts

@@ -3,7 +3,7 @@
  *
  * Substring hits first (they meant that name), then the Foldspace SDK's
  * `searchInList` (Fuse) for typos. Do not use this for domain ranking
- * (invoices, coverage, MasterFormat).
+ * (invoices, coverage, industry classification codes).
  */
 
 import { getAgent } from "./agent";

package/src/runtime/render.ts

@@ -5,6 +5,8 @@
  * use `innerHTML` with API data.
  */
 
+import type { ApiFailure } from "./http";
+
 /**
  * The `host` argument Foldspace passes to `render`, or `{ container }` from
  * older tenant helpers. Either works.
@@ -44,7 +46,7 @@ export function renderLoading(host: ViewHost, message = "Working..."): void {
  * panel that does not name the query reads as a failure.
  *
  * @param host - Foldspace `render` host
- * @param message - Include the query, e.g. `No estimates matching "Webb"`
+ * @param message - Include the query, e.g. `No projects matching "Acme"`
  */
 export function renderEmpty(host: ViewHost, message: string): void {
   replace(host, el("div", "fs-state fs-empty", message));
@@ -95,3 +97,42 @@ export function renderFatal(
   }
   replace(host, wrap);
 }
+
+/**
+ * Pick the right state for a failed call, so every action handles the boring
+ * failures the same way and none of them renders as a blank or a success card.
+ *
+ * - `not_found` → {@link renderEmpty}. Nothing matching is an answer, not an error.
+ * - `signed_out` → {@link renderFatal}, with your same-tab sign-in link if given.
+ * - `forbidden` / `config` / `unreachable` → {@link renderFatal}. Retrying cannot help.
+ * - `rate_limited` / `timeout` / `server` → {@link renderError}, with retry.
+ *
+ * @param host - Foldspace `render` host
+ * @param failure - The `{ ok: false }` half of an `ApiResult`
+ * @param options - `notFound`: name what was looked for. `signIn`: same-tab link.
+ */
+export function renderFailure(
+  host: ViewHost,
+  failure: ApiFailure,
+  options: {
+    onRetry?: () => void;
+    signIn?: { label: string; href: string };
+    notFound?: string;
+  } = {},
+): void {
+  switch (failure.reason) {
+    case "not_found":
+      renderEmpty(host, options.notFound ?? failure.error);
+      return;
+    case "signed_out":
+      renderFatal(host, failure.error, options.signIn);
+      return;
+    case "forbidden":
+    case "config":
+    case "unreachable":
+      renderFatal(host, failure.error);
+      return;
+    default:
+      renderError(host, failure.error, options.onRetry);
+  }
+}

package/templates/agent-starter/agent/actions/_example.ts

@@ -1,6 +1,9 @@
 // Copy this file to <action_key>.ts and register it in index.ts.
 // Do not register _example — it is not a real Agent Studio action.
 //
+// This is an empty skeleton. For a finished experience — handler, card with
+// every state, fixtures — read node_modules/@foldspace_npm/harness/recipes/INDEX.md.
+//
 // Import helpers from ../utils, not from @foldspace_npm/harness/runtime.
 // The path below is a placeholder until you capture a real HTTP 200.
 
@@ -14,7 +17,9 @@ export const example_action = {
 
     const result = await apiFetch<{ items?: Item[] }>("/__observe_me");
     if (!result.ok) {
-      return { ok: false, error: result.error };
+      // Pass `reason` through so `render` can call renderFailure — an expired
+      // session, a 404 and a throttled call are three different widget states.
+      return { ok: false, error: result.error, reason: result.reason };
     }
 
     const items = result.data.items ?? [];
@@ -23,6 +28,8 @@ export const example_action = {
       idOf: (item) => item.id,
     });
 
-    return { ok: true, matches };
+    // Zero matches is an answer, not an error. Return the query so the empty
+    // state can name what was searched for.
+    return { ok: true, query, matches };
   },
 };

package/templates/agent-starter/agent/utils.ts

@@ -27,6 +27,8 @@
  *
  * Widget chrome (unstyled; replace in `agent/views/` when brand matters):
  * - `renderLoading` / `renderEmpty` / `renderError` / `renderFatal`
+ * - `renderFailure` — picks one of those from `ApiFailure.reason`, so an expired
+ *   session, a 404 and a throttled call each draw the right state.
  *
  * Config (already called above; you rarely need these in an action):
  * - `configure` / `getConfig`