@foldspace_npm/harness 0.1.8 → 0.1.10

package/src/runtime/config.ts

@@ -0,0 +1,78 @@
+/**
+ * Tenant-specific facts for the page runtime. Set once from `agent/utils.ts`.
+ *
+ * This module cannot import the client's `constants.ts`, so the client pushes
+ * values in with {@link configure}. Nothing here is a Foldspace cloud setting.
+ */
+
+/**
+ * Where the customer app keeps its own session token — not a Foldspace token.
+ *
+ * Custom headers (not Bearer) are out of scope: override `apiFetch` in
+ * `agent/utils.ts` instead of adding a third `kind`.
+ */
+export interface AuthSource {
+  /** Where the live page stores the token. */
+  kind: "localStorage" | "cookie";
+  /** The localStorage key or cookie name observed on the page. */
+  name: string;
+}
+
+/**
+ * Values {@link configure} stores for the rest of the runtime.
+ *
+ * Stamp `apiBase` and `authSource` empty until you capture a real XHR. A
+ * guessed host or Bearer vs cookie looks like success and publishes to the
+ * wrong place.
+ */
+export interface RuntimeConfig {
+  /** Foldspace agent apiName, e.g. `joist-agent`. */
+  agentApiName: string;
+  /**
+   * Prefix for `apiFetch` / `apiFetchBinary`. Include an explicit port if the
+   * app uses one — omitting `:443` can fail CORS.
+   */
+  apiBase?: string;
+  /**
+   * Prefix for `publicFetch` when the caller does not pass an origin.
+   * Marketing / unauthenticated hosts only.
+   */
+  publicOrigin?: string;
+  /** Session location for `getAuthToken`. Omit until observed. */
+  authSource?: AuthSource;
+  /** `fetch` timeout in ms. Defaults to 15_000 in `configure`. */
+  timeoutMs?: number;
+}
+
+let config: RuntimeConfig | null = null;
+
+/**
+ * Store tenant config for this page bundle. Call once from `agent/utils.ts`
+ * at module load — not from an action `execute`.
+ *
+ * Replaces the previous object; it does not merge. A second call clobbers the
+ * first. `timeoutMs` defaults to 15_000 if omitted.
+ *
+ * @param next - Tenant ids and observed API/auth facts
+ */
+export function configure(next: RuntimeConfig): void {
+  config = { timeoutMs: 15_000, ...next };
+}
+
+/**
+ * Read the config {@link configure} stored.
+ *
+ * Throws if `configure` never ran (imported the runtime without going through
+ * `agent/utils.ts`). Empty `apiBase` / `authSource` after configure is valid;
+ * `apiFetch` returns `{ ok: false }` for those instead of throwing.
+ *
+ * @returns The singleton config for this bundle
+ */
+export function getConfig(): RuntimeConfig {
+  if (!config) {
+    throw new Error(
+      "harness runtime is not configured — call configure() from agent/utils.ts",
+    );
+  }
+  return config;
+}

package/src/runtime/http.ts

@@ -0,0 +1,373 @@
+// HTTP against the customer's own API, from inside their signed-in page.
+//
+// Lifted from the Transparency Catalog 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
+// apiFetch, not here.
+
+import { getConfig } from "./config";
+
+/**
+ * Mask a secret for logs. Never log a raw token.
+ *
+ * @param value - Token or other secret; null/empty becomes `"<empty>"`
+ * @returns `"<redacted:N chars>"` or `"<empty>"`
+ */
+export function redact(value: string | null | undefined): string {
+  if (!value) return "<empty>";
+  return `<redacted:${value.length} chars>`;
+}
+
+function readLocalStorageValue(key: string): string | null {
+  const raw = window.localStorage.getItem(key);
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "string") return parsed;
+    if (parsed && typeof parsed === "object") {
+      return parsed.access_token ?? parsed.token ?? parsed.value ?? null;
+    }
+  } catch {
+    return raw;
+  }
+  return raw;
+}
+
+function readCookie(name: string): string | null {
+  const prefix = `${name}=`;
+  for (const part of document.cookie.split(";")) {
+    const c = part.trim();
+    if (c.startsWith(prefix)) {
+      return decodeURIComponent(c.slice(prefix.length)) || null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Read the customer app's session token from `authSource`.
+ *
+ * Returns null when unsigned-in, `AUTH_SOURCE` is unset, or the key is empty.
+ * This is the host app token, not a Foldspace credential.
+ *
+ * @returns The token string, or `null`
+ */
+export function getAuthToken(): string | null {
+  const source = getConfig().authSource;
+  if (!source?.name) return null;
+  if (source.kind === "cookie") return readCookie(source.name);
+  return readLocalStorageValue(source.name);
+}
+
+/**
+ * Decode a JWT payload without verifying the signature.
+ *
+ * Identity hints only (email, sub). Never use this for authorization.
+ *
+ * @param token - Compact JWT from {@link getAuthToken}
+ * @returns Parsed payload, or `null` if the token is not a JWT
+ */
+export function parseJwt<T = Record<string, unknown>>(token: string): T | null {
+  try {
+    const [, payload] = token.split(".");
+    if (!payload) return null;
+    const json = atob(payload.replace(/-/g, "+").replace(/_/g, "/"));
+    return JSON.parse(json) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Successful JSON/binary response from {@link apiFetch}, {@link apiFetchBinary},
+ * or {@link publicFetch}.
+ */
+export interface ApiSuccess<T> {
+  ok: true;
+  /** HTTP status (typically 200). */
+  status: number;
+  /** Parsed JSON (`apiFetch` / `publicFetch`) or bytes (`apiFetchBinary`). */
+  data: T;
+}
+
+/**
+ * Failed request. Errors are **returned**, never thrown.
+ *
+ * Show `error` to a person. Log `detail` to the console only — never put
+ * `detail` in an action return value; Foldspace may quote that to the user.
+ *
+ * `unreachable` is true when the browser never got a response (DNS, CORS,
+ * 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.
+ */
+export interface ApiFailure {
+  ok: false;
+  /** HTTP status, or `0` when there was no response / config was missing. */
+  status: number;
+  /** Safe, user-facing sentence. Pass this to `renderError`. */
+  error: string;
+  /** Truncated API body for the console. Never show this in the widget. */
+  detail?: string;
+  /**
+   * True when the network itself failed (not HTTP 4xx/5xx, not abort).
+   * Use this to distinguish "server said no" from "could not reach host".
+   */
+  unreachable?: boolean;
+}
+
+/** Discriminated result of a customer-API call. Branch on `ok`. */
+export type ApiResult<T> = ApiSuccess<T> | ApiFailure;
+
+function missingConfigResult(): ApiResult<never> | null {
+  const config = getConfig();
+  if (!config.apiBase) {
+    return {
+      ok: false,
+      status: 0,
+      error: "API_BASE is not set — capture the app's XHR first.",
+    };
+  }
+  if (!config.authSource) {
+    return {
+      ok: false,
+      status: 0,
+      error: "AUTH_SOURCE is not set — capture the app's session first.",
+    };
+  }
+  return null;
+}
+
+function failureDetail(parsed: unknown): string | undefined {
+  if (parsed && typeof parsed === "object") {
+    const m = (parsed as { message?: unknown }).message;
+    if (typeof m === "string") return m.slice(0, 300);
+  } else if (typeof parsed === "string" && parsed.trim()) {
+    return parsed.trim().slice(0, 300);
+  }
+  return undefined;
+}
+
+/**
+ * Authenticated JSON request against `apiBase` with `Authorization: Bearer`.
+ *
+ * Matches the common pattern (two of three early builds). If the live page
+ * uses cookies, custom headers, or no Bearer, **stop re-exporting this** from
+ * `agent/utils.ts` and write a local `apiFetch` instead.
+ *
+ * Empty `API_BASE` / `AUTH_SOURCE` return `{ ok: false }` so a guessed host
+ * cannot look like success. Errors never throw and never include the token.
+ *
+ * @param path - Path under `apiBase`, including a leading `/`
+ * @param init - Extra `fetch` options; your headers merge over Bearer/JSON
+ * @param timeoutMs - Override the configured timeout (default 15s)
+ */
+export async function apiFetch<T = unknown>(
+  path: string,
+  init: RequestInit = {},
+  timeoutMs?: number,
+): Promise<ApiResult<T>> {
+  const missing = missingConfigResult();
+  if (missing) return missing;
+
+  const token = getAuthToken();
+  if (!token) return { ok: false, status: 401, error: "Not signed in." };
+
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(),
+    timeoutMs ?? getConfig().timeoutMs ?? 15_000,
+  );
+
+  try {
+    const res = await fetch(`${getConfig().apiBase}${path}`, {
+      ...init,
+      signal: controller.signal,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+        ...(init.headers ?? {}),
+      },
+    });
+
+    const text = await res.text();
+    let parsed: unknown = text;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      /* non-JSON; keep the raw text for the status check */
+    }
+
+    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 { 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.",
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Run an async worker over a list with a cap on in-flight work.
+ *
+ * Use this for N+1 fetches after a list call (export, hydrate rows). A large
+ * list without a cap can open dozens of sockets at once.
+ *
+ * @param items - Inputs to process
+ * @param limit - Max concurrent `worker` calls
+ * @param worker - Async mapper; results stay in input order
+ */
+export async function mapWithConcurrency<T, R>(
+  items: T[],
+  limit: number,
+  worker: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  let cursor = 0;
+  const runners = Array.from(
+    { length: Math.min(limit, items.length) || 0 },
+    async () => {
+      while (cursor < items.length) {
+        const i = cursor++;
+        results[i] = await worker(items[i], i);
+      }
+    },
+  );
+  await Promise.all(runners);
+  return results;
+}
+
+/**
+ * Same auth and `apiBase` as {@link apiFetch}, but returns raw bytes.
+ *
+ * Use for file downloads / exports, not JSON endpoints.
+ *
+ * @param path - Path under `apiBase`, including a leading `/`
+ * @param init - Extra `fetch` options
+ * @param timeoutMs - Override the configured timeout (default 15s)
+ */
+export async function apiFetchBinary(
+  path: string,
+  init: RequestInit = {},
+  timeoutMs?: number,
+): Promise<ApiResult<Uint8Array>> {
+  const missing = missingConfigResult();
+  if (missing) return missing;
+
+  const token = getAuthToken();
+  if (!token) return { ok: false, status: 401, error: "Not signed in." };
+
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(),
+    timeoutMs ?? getConfig().timeoutMs ?? 15_000,
+  );
+
+  try {
+    const res = await fetch(`${getConfig().apiBase}${path}`, {
+      ...init,
+      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.",
+      };
+    }
+    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.",
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * 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.
+ *
+ * @param path - Path under the public origin
+ * @param origin - Override `publicOrigin` for this call
+ * @param timeoutMs - Override the configured timeout (default 15s)
+ */
+export async function publicFetch<T = unknown>(
+  path: string,
+  origin?: string,
+  timeoutMs?: number,
+): Promise<ApiResult<T>> {
+  const base = origin ?? getConfig().publicOrigin;
+  if (!base) {
+    return {
+      ok: false,
+      status: 0,
+      error: "No public origin is configured for this app.",
+    };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(),
+    timeoutMs ?? getConfig().timeoutMs ?? 15_000,
+  );
+  try {
+    const res = await fetch(`${base}${path}`, {
+      credentials: "include",
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      return {
+        ok: false,
+        status: res.status,
+        error: "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.",
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Page-runtime helpers compiled into the customer's bundle via esbuild.
+ *
+ * Source is TypeScript on purpose: what you read here is what ships. Import
+ * these from `agent/utils.ts` in the client repo, not from this package path
+ * inside an action file.
+ *
+ * @packageDocumentation
+ */
+
+export { configure, getConfig } from "./config";
+export type { RuntimeConfig, AuthSource } from "./config";
+
+export { getAgent, armAllInstances } from "./agent";
+
+export {
+  redact,
+  getAuthToken,
+  parseJwt,
+  apiFetch,
+  apiFetchBinary,
+  publicFetch,
+  mapWithConcurrency,
+} from "./http";
+export type { ApiResult, ApiSuccess, ApiFailure } from "./http";
+
+export { rankBy } from "./match";
+export type { FuzzyMatch, RankByOptions } from "./match";
+
+export {
+  renderLoading,
+  renderEmpty,
+  renderError,
+  renderFatal,
+} from "./render";
+export type { ViewHost } from "./render";

package/src/runtime/match.ts

@@ -0,0 +1,87 @@
+/**
+ * Rank an in-memory list against what a user typed.
+ *
+ * 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).
+ */
+
+import { getAgent } from "./agent";
+
+/** One SDK fuzzy hit. `score` is lower-is-better Fuse scoring. */
+export interface FuzzyMatch<T> {
+  item: T;
+  score?: number;
+}
+
+/**
+ * Options for {@link rankBy}.
+ */
+export interface RankByOptions<T> {
+  /** Fields to match, in priority order. */
+  searchKeys: (keyof T & string)[];
+  /** Stable identity so substring and fuzzy hits can be merged. */
+  idOf: (item: T) => string | number;
+  /** Max rows to return. Default 10. */
+  limit?: number;
+  /**
+   * Drop SDK hits with score at or above this. Default 0.45. Lower is a
+   * closer Fuse match.
+   */
+  plausible?: number;
+}
+
+/** Lower is better in the SDK's scoring. Above this, a hit is noise. */
+const PLAUSIBLE = 0.45;
+
+/**
+ * Rank records against a user's phrase.
+ *
+ * If `searchInList` is missing, the substring pass still answers — a missing
+ * SDK method degrades the result rather than breaking the action.
+ *
+ * @param items - Records already loaded (e.g. from {@link apiFetch})
+ * @param query - What the user typed
+ * @param opts - Fields, identity, optional limit
+ * @returns Up to `limit` items, substring matches first
+ */
+export function rankBy<T>(
+  items: T[],
+  query: string,
+  opts: RankByOptions<T>,
+): T[] {
+  const limit = opts.limit ?? 10;
+  const q = query.trim();
+  if (!q) return items.slice(0, limit);
+
+  const needle = q.toLowerCase();
+  const substring = items.filter((item) =>
+    opts.searchKeys.some((k) =>
+      String(item[k] ?? "")
+        .toLowerCase()
+        .includes(needle),
+    ),
+  );
+
+  let fuzzy: T[] = [];
+  try {
+    const hits: FuzzyMatch<T>[] =
+      getAgent()?.searchInList?.(items, q, { searchKeys: opts.searchKeys }) ??
+      [];
+    fuzzy = hits
+      .filter((h) => (h.score ?? 1) < (opts.plausible ?? PLAUSIBLE))
+      .map((h) => h.item);
+  } catch (err) {
+    console.warn("[foldspace] fuzzy search unavailable:", err);
+  }
+
+  const seen = new Set(substring.map(opts.idOf));
+  const merged = [...substring];
+  for (const item of fuzzy) {
+    const id = opts.idOf(item);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    merged.push(item);
+  }
+  return merged.slice(0, limit);
+}

package/src/runtime/render.ts

@@ -0,0 +1,97 @@
+/**
+ * Unstyled chatterblock states. Tenant brand belongs in `agent/views/`.
+ *
+ * An action's `render` output cannot be typechecked. Look at a frame. Never
+ * use `innerHTML` with API data.
+ */
+
+/**
+ * The `host` argument Foldspace passes to `render`, or `{ container }` from
+ * older tenant helpers. Either works.
+ */
+export type ViewHost = HTMLElement | { container: HTMLElement };
+
+function containerOf(host: ViewHost): HTMLElement {
+  return host instanceof HTMLElement ? host : host.container;
+}
+
+function el(tag: string, className: string, text?: string): HTMLElement {
+  const node = document.createElement(tag);
+  node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function replace(host: ViewHost, node: HTMLElement): void {
+  const container = containerOf(host);
+  container.textContent = "";
+  container.appendChild(node);
+}
+
+/**
+ * In-progress chatterblock. Unstyled scaffolding — replace with branded UI
+ * when the card is the experience.
+ *
+ * @param host - Foldspace `render` host
+ * @param message - Short status text. Default `"Working..."`.
+ */
+export function renderLoading(host: ViewHost, message = "Working..."): void {
+  replace(host, el("div", "fs-state fs-loading", message));
+}
+
+/**
+ * Nothing matched, but nothing went wrong. Say what was searched for — an empty
+ * 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"`
+ */
+export function renderEmpty(host: ViewHost, message: string): void {
+  replace(host, el("div", "fs-state fs-empty", message));
+}
+
+/**
+ * Recoverable error: the user can retry or narrow. Pass `ApiResult.error`,
+ * never `detail` — `detail` is the API's own words and is for the console.
+ *
+ * @param host - Foldspace `render` host
+ * @param message - Safe, user-facing sentence
+ * @param onRetry - Optional click handler for a "Try again" button
+ */
+export function renderError(
+  host: ViewHost,
+  message: string,
+  onRetry?: () => void,
+): void {
+  const wrap = el("div", "fs-state fs-error");
+  wrap.appendChild(el("p", "fs-error-message", message));
+  if (onRetry) {
+    const btn = el("button", "fs-retry", "Try again") as HTMLButtonElement;
+    btn.addEventListener("click", onRetry);
+    wrap.appendChild(btn);
+  }
+  replace(host, wrap);
+}
+
+/**
+ * Unrecoverable: retrying cannot help (signed out, host refused). Optional
+ * same-tab link — do not open a second tab out of the host app.
+ *
+ * @param host - Foldspace `render` host
+ * @param message - Safe, user-facing sentence
+ * @param action - Optional `{ label, href }` rendered as a same-tab `<a>`
+ */
+export function renderFatal(
+  host: ViewHost,
+  message: string,
+  action?: { label: string; href: string },
+): void {
+  const wrap = el("div", "fs-state fs-fatal");
+  wrap.appendChild(el("p", "fs-error-message", message));
+  if (action) {
+    const a = el("a", "fs-fatal-action", action.label) as HTMLAnchorElement;
+    a.href = action.href;
+    wrap.appendChild(a);
+  }
+  replace(host, wrap);
+}