cfo-os / web /src /query /queryApi.ts
fsanyoto's picture
Deploy AIOS web (React glide grid + FastAPI slice)
6c9f944 verified
Raw History Blame Contribute Delete
7.07 kB
// ---------------------------------------------------------------------------
// query/queryApi.ts β€” WAVE 32 item 7 (ruling R1, contract C5): the four calls,
// and nothing else.
//
// Shaped like `alerts/alertsApi.ts` β€” the same `Result<T>`, the same 4xx/5xx
// message split β€” because the failure that matters is identical: a wrong
// `credentials` word produces no client-side symptom at all, just a 401 from a
// server that never saw a session.
//
// β›” A REFUSAL IS A 200 HERE, AND THAT IS THE CONTRACT, NOT A LOOSE END. C5's
// promise is that a question the backend cannot express gets "a plain sentence,
// not a broken view", so `build` answers `{spec: null, refused: "<sentence>"}`
// with an OK status. Mapping it onto an error would paint the error page the
// ruling exists to prevent. The 4xx cases are the ones that really are the
// caller's fault: no database named, no question, a database this session may
// not open.
//
// ⚠ NO CLIENT UNION OVER `kind`. It is the server's vocabulary and arrives as a
// string (the wave-9 law): a client `type Kind = "grid" | …` turns "the server
// added a kind" into "the client drops the view".
// ---------------------------------------------------------------------------
import { API_V1, CREDENTIALS } from "../apiContract";
export type Result<T> =
| { ok: true; value: T }
| { ok: false; status: number; message: string };
/** One saved AI-built view, as `GET /query` sends it. */
export interface SavedQuery {
id: string;
scope: string;
viewId: string;
name: string;
/** A STRING, never a union β€” see the header. */
kind: string;
question: string;
explain: string;
createdAt?: string;
}
/** What `POST /query/build` answers. Exactly one of `spec` / `refused` is set. */
export interface BuildResult {
spec: unknown | null;
explain: string | null;
refused: string | null;
/** The machine-readable cause behind `refused`, when the server names one. */
reason?: string;
id?: string;
/**
* β›” TRUE when the answer came from a rung BELOW the top of the server's provider ladder.
*
* The server has always known which model answered and has always sent it; nothing read it.
* It matters because the rungs are not interchangeable: `_call_model`'s own docstring records
* that only the FIRST provider is measured to refuse honestly, and *"the ones below it answer
* unanswerable questions with plausible specs"*. So when the top rung is rate-limited the
* ladder falls through β€” correctly, a Query module that dies whenever one free tier 429s is
* worse β€” and the person is then reading a confident, well-formed view built by a model that
* does not know how to say "this database cannot answer that". This flag is the only thing
* that distinguishes those two answers on screen.
*/
fallback?: boolean;
}
/** 4xx text is POLICY the reader needs ("this database does not have …"); a 5xx's
* text is the server's internals and is never shown. Same split as alertsApi. */
export function errorMessage(status: number, message?: string): string {
if (status >= 500 || !message) {
return status >= 500
? "Something went wrong on our side. Try again in a moment."
: `The server answered ${status}.`;
}
return message;
}
async function call<T>(
path: string,
init: RequestInit,
read: (body: unknown) => T
): Promise<Result<T>> {
let res: Response;
try {
res = await fetch(`${API_V1}${path}`, { credentials: CREDENTIALS, ...init });
} catch {
return { ok: false, status: 0, message: "Cannot reach the server." };
}
const body = (await res.json().catch(() => null)) as unknown;
if (!res.ok) {
const detail = (body as { error?: { message?: string } } | null)?.error?.message;
return { ok: false, status: res.status, message: errorMessage(res.status, detail) };
}
return { ok: true, value: read(body) };
}
const json = (data: unknown): RequestInit => ({
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(data),
});
const str = (v: unknown): string => (typeof v === "string" ? v : "");
/** Fails CLOSED: an unreadable answer is an empty list, never a half-parsed one. */
export function parseSaved(body: unknown): SavedQuery[] {
const rows = (body as { views?: unknown[] } | null)?.views;
if (!Array.isArray(rows)) return [];
return rows
.map((r) => r as Record<string, unknown>)
.filter((r) => r && str(r.id) && str(r.scope))
.map((r) => ({
id: str(r.id),
scope: str(r.scope),
viewId: str(r.viewId) || str(r.id),
name: str(r.name) || "Query",
kind: str(r.kind) || "grid",
question: str(r.question),
explain: str(r.explain),
createdAt: str(r.createdAt) || undefined,
}));
}
/** `GET /query`: the saved views AND the built-in scopes the build door accepts. */
export interface QueryIndex {
views: SavedQuery[];
/**
* The non-`ut_` scopes `POST /query/build` will accept, published by the server.
*
* β›” THE PICKER MIRRORS THIS INSTEAD OF GUESSING. The nav hands this page every granted entry,
* which is a WIDER set than the build door accepts β€” a picker filtered on "not a surface" alone
* offers databases that 404. `view_templates`' rule: a picker that offers what the door would
* refuse is a control that lies.
*/
builtins: string[];
}
export function fetchQueries(): Promise<Result<QueryIndex>> {
return call("/query", {}, (b) => ({
views: parseSaved(b),
builtins: (((b as { builtins?: unknown } | null)?.builtins as unknown[]) ?? [])
.filter((k): k is string => typeof k === "string"),
}));
}
/**
* Ask for a view. **This writes nothing** β€” the spec comes back for a person to
* read before `saveQuery` stores it, which is the only check on the one failure
* class no validator can see (a well-formed spec that answers a different
* question). See `routes_query.py`'s header.
*/
export function buildQuery(question: string, scope: string): Promise<Result<BuildResult>> {
return call("/query/build", json({ question, scope }), (b) => {
const r = (b || {}) as Record<string, unknown>;
return {
spec: r.spec ?? null,
explain: str(r.explain) || null,
refused: str(r.refused) || null,
reason: str(r.reason) || undefined,
id: str(r.id) || undefined,
// ⚠ `=== true`, not truthy: an absent key must read as "not a fallback", and a server that
// has not been redeployed yet sends nothing at all. Fail-quiet is right here β€” the wrong
// direction would be warning about every answer on an older build.
fallback: r.fallback === true,
};
});
}
export function saveQuery(
question: string,
scope: string,
spec: unknown
): Promise<Result<SavedQuery>> {
return call("/query/save", json({ question, scope, spec }), (b) => parseSaved({ views: [b] })[0]);
}
export function deleteQuery(id: string): Promise<Result<true>> {
return call(`/query/${encodeURIComponent(id)}`, { method: "DELETE" }, () => true as const);
}