OpenBot Data Access
When To Use
This skill applies to any change under app/src that moves data between the browser and the API
server. It fires on new screens, new endpoints, new query keys, on any change to api/openapi.yaml,
and on any diff that introduces fetch anywhere but app/src/lib/client.ts.
It does not cover the server's handlers, zod form schemas (lib/<entity>/form.ts), or page
layout. It does cover lib/copilot/: the conversation itself streams over AG-UI, but the tool calls a
Bot makes during a turn are ordinary authenticated requests and go through the client like everything
else.
API First
OpenBot's API is described in api/openapi.yaml (OpenAPI 3.1), and that file is the single source of
truth: the browser's client, its types, the server's types, the docs and the contract tests all come
from it. It is a bundle of one source file per area under api/openapi/; edit those, never the
bundle (api/README.md). The WebSocket channels are described beside it in api/asyncapi.yaml. It follows CopilotKit Intelligence's v2 conventions so the two read as one API: every
resource under /api/v2/organizations/{organizationId}/, errors as application/problem+json, lists
paged with cursor and limit (answering nextCursor), and an Idempotency-Key on every write.
Resources move into the spec one area at a time. Most are in it now (api/README.md lists the area
files); an operation that is not is still reached the older way, through client, until its turn. So there are two
kinds of request, and which one a call is depends only on whether its operation is in the spec:
- An operation in the spec is called through the function Orval generated for it
(
listBots,createBot, …, in@/lib/api/generated/<tag>/<tag>), with types from@/lib/api/generated/model. Neverclient(path, …), never a hand-written type for its payload. - Anything else goes through
clientexactly as described below.
The generated functions all run through apiRequest in lib/api/request.ts (Orval's mutator), which
is built on clientRequest in lib/client.ts: the same session cookie, and a refusal is the same
ClientError carrying the server's own sentence (error today, detail in problem details) or the
fallback the caller passes. A screen cannot tell which kind of request it made.
organizationId() is the organization the person is working in (lib/organizations/current.ts).
A person can belong to several; the app learns which one from the list of their own before it asks
for anything else, and a call made before that throws instead of guessing. Call it where the request
is made, never keep it in a constant. The query client keeps every cached answer under the
organization it was asked in (query-client.ts), so a key factory does not name the organization
itself.
The generated code is checked in. CI regenerates it and fails when it differs, lints the spec, and
fails a pull request that breaks a client of the base branch's spec (oasdiff). A change that takes
nothing from a client, such as writing down a rule the server already enforces, goes through only
when it is listed with its reason in api/accepted-breaking-changes.md. A new hand-written address
of the server, or a request sent by hand, fails api/client-boundary.test.ts unless
api/client-boundary.allow.ts names it with the rule it follows.
The Shape
Every entity the browser knows about owns a directory under app/src/lib/:
api/openapi/<area>.yaml # the contract's sources, one file per area
api/openapi.yaml # the contract, bundled from them
app/src/lib/
client.ts # the only fetch in the app
api/
request.ts # Orval's mutator: apiRequest, organizationId(), idempotencyKey()
generated/ # Orval's output: functions, hooks, types, Zod schemas, MSW handlers
<entity>/
queries.ts # read types, key factory, queryOptions factories
mutations.ts # input type, mutationOptions factories
form.ts # zod schema (a different skill's territory)client.ts owns the transport: credentials, the JSON content type, body serialisation, and turning a
failed status into an Error carrying the server's own message. It owns nothing about meaning — the
envelope key and the sentence a person reads stay at the call site, because those are facts about one
endpoint rather than about requests in general.
client<T>(path, key, options?): Promise<T> // parsed, and `key` unwrapped
client(path, options?): Promise<Response> // for a caller that only needed it to work
tryClient(path, options?): Promise<Response> // never throws; the status is the answeroptions is { method?, body?, fallback?, signal? }. body is serialised by the client, which is
also what sets the content type — so a caller passes an object, never a string. Passing
JSON.stringify(x) sends a JSON string of a JSON string, which no endpoint accepts.
Three kinds of request
Not everything crossing the wire is cached state, and the shape follows from which kind it is.
- A cached read is a
queryOptionsfactory inqueries.ts. It has a key, and something can invalidate it. - A write somebody asked for is a
mutationOptionsfactory inmutations.ts. It invalidates on success. - Everything else is a plain exported function, living beside the factories for its entity.
A verdict about this moment (
decideComponent,testAgentConnection), a tool call during a Bot's turn (callPluginTool, the computer control surface), a frame of a screen, a step inside another write (storeMcpToken). These fail closed and return a value rather than throwing, because a refusal is usually the answer. Giving one a cache key would create a key nothing reads and an invalidation nothing triggers.
The third kind still lives under lib/. It is not licence to call the server from a component.
There is one of these per entity (agents, audit, auth, channels, components, computers,
credentials, package, plugins, routines, skills and the rest). They all look the
same on purpose. lib/agents/queries.ts and lib/agents/mutations.ts are the reference pair; read them
before writing a new one.
The one rule that matters: a React component never calls fetch. If a component file contains
fetch, the change is wrong regardless of whether it works.
And its companion: a component never imports from lib/api/generated either. The generated
functions are called from the entity's factories, which give the result the entity's own cache key.
The generated use* hooks and get*QueryOptions key their cache by URL, which no <entity>Keys.all
invalidation reaches, so a screen on a generated hook shows a second, stale copy of data the
factories already hold.
Procedures
Procedure 0: Add or change an operation in the spec
- Write it in its area's file under
api/openapi/first, before any client or server code (a new path also gets one line inapi/openapi/common.yaml;api/README.mdhas the rule). Copy the shape of an operation already there: the sharedOrganizationId,Limit,CursorandIdempotencyKeyparameters, aProblemresponse for every 4xx and 5xx,securitynaming who may call it. Describe what the server does; never invent a field it does not return. bun run api:lint. It refuses a path outside/api/v2/organizations/{organizationId}/, a path Intelligence already serves (api/intelligence-reserved.yaml), a write with noIdempotency-Key, an error that is not problem details, and a list that does not page.bun run api:generate, which bundlesapi/openapi.yamland then generates the client, and commit the area file, the bundle andapp/src/lib/api/generatedtogether. Never edit the bundle or a generated file: change the area file and generate again.- Call the new function from the entity's factory (Procedures 1 and 2): pass
organizationId(), afallbacksentence, and on a write{ "Idempotency-Key": idempotencyKey() }. Unwrap the envelope (.bot,.bots) in the factory, so components see the payload. A list reads every page untilnextCursoris null (everyBotinlib/agents/queries.ts). - Make the entity's type the generated one (
export type AgentProfile = Bot), so the browser's type and the spec cannot drift. Test fixtures typed with it then need every field the spec requires. - Changing a published operation: removing or renaming a field, making a request field required, or removing an operation fails CI's breaking-change check. Add instead: a new optional field, a new operation.
Procedure 1: Add a read
Create or open
app/src/lib/<entity>/queries.ts.Declare the browser-shaped type for the payload —
<Entity>Profile,<Entity>Status,<Entity>Summary, or<Entity>Record, matching whichever sibling name fits. This type describes what the browser receives, not what the database stores.Include the server's authorization verdicts as fields on that type (
canManage,systemOwned,mine,hasAuth) and document them. The browser renders these flags; it never recomputes ownership or permission rules from other fields.Never put a secret's value in a read type. A credential is
hasAuth: booleanor arevokedAttimestamp. Secrets are write-only in this codebase.Add or extend the key factory, named
<entity>Keys:export const agentKeys = { all: ["agents"] as const, list: (hidden = false) => ["agents", "list", { hidden }] as const, detail: (agentId: string) => ["agents", "detail", agentId] as const, };allis always the bare entity name and is the invalidation root. List keys carry their parameters as a trailing object so two filters are two cache entries. Every array isas const. A single-key entity still gets a factory:export const packageKeys = { active: ["tenant-package", "active"] as const };.Export a factory function returning
queryOptions({ queryKey, queryFn }), named<subject>QueryOptions. Existing spellings:agentListQueryOptions,agentQueryOptions,agentComponentsQueryOptions,activePackageQueryOptions.Inside
queryFn, call the generated function when the operation is in the spec (Procedure 0, step 4):queryFn: async (): Promise<AgentProfile> => (await getBot(organizationId(), agentId, { fallback: "Couldn't load this Bot." })).bot,Otherwise call
clientwith the path, the envelope key, and afallbacksentence. It sends the credentials, checks the status, raises the server's message when there is one, and unwraps the key so the caller receives the payload rather than the wrapper:queryFn: (): Promise<LearningSettings> => client("/api/admin/learning/settings", "settings", { fallback: "Learning settings could not be loaded.", }),Where the whole body is the payload, omit the key and read it:
(await client(path, { fallback })).json(). Where a failed status is an answer rather than an error — a refused component call, a 401 that means "not signed in" — usetryClientand read the status.Annotate the
queryFnreturn type explicitly ((): Promise<AgentProfile[]>).clientis generic in its payload, so the annotation is what fixes what the key unwraps to.
Procedure 2: Add a write
Create or open
app/src/lib/<entity>/mutations.ts.Declare the input type as
<Entity>Input— the shape the API accepts, which is not the form's shape. Mapping between them isform.ts's job (agentInputFrom).Call the generated function when the operation is in the spec, with a fresh
Idempotency-Keyfor each write a person asks for:mutationFn: async (input: AgentInput): Promise<AgentProfile> => (await createBot(organizationId(), input, { "Idempotency-Key": idempotencyKey() }, { fallback: FALLBACK, })).bot,idempotencyKey(), nevercrypto.randomUUID(): the latter exists only in a secure context, and a self-hosted OpenBot opened at a plain-HTTP address is not one.Otherwise call
client. Do not write a per-entity request helper —agentRequest,componentRequestand two others each owned a private copy of the same credentials, headers and error extraction, and one of the four had quietly dropped the extraction.clientowns it now:mutationFn: (settings: LearningSettings): Promise<LearningSettings> => client("/api/admin/learning/settings", "settings", { method: "PUT", body: settings, fallback: FALLBACK, }),Where the write returns nothing a caller needs, omit the key and
await client(path, { ... }). Keep oneconst FALLBACKper file rather than repeating the sentence: the reader of the failure cares which entity failed, and within one file that never changes.Export one factory per write, named
<verb><Entity>MutationOptions(queryClient), returningmutationOptions({ mutationFn, onSuccess }). Existing spellings:createAgentMutationOptions,updateAgentMutationOptions,duplicateAgentMutationOptions,setAgentHiddenMutationOptions,deleteAgentMutationOptions.Give
mutationFnexactly one parameter. For a single value that is the value (agentId: string); for more than one it is a namedvariablesobject ({ agentId: string; input: AgentInput }).Invalidate on success — never patch the cache by hand:
onSuccess: () => queryClient.invalidateQueries({ queryKey: agentKeys.all })With several writes in one file, wrap that in a private
invalidate<Entity>(queryClient)helper. Server-derived fields are the reason: a hand-patched cache entry is a guess at what the server decided, and it is wrong the first time the server adds a rule.queryClient.removeQueriesinstead ofinvalidateQuerieswhen the data should stop existing rather than be refetched. Sign-out is the only current case (lib/auth/mutations.ts).A fire-and-forget write takes no
queryClientand has noonSuccess(recordChannelActivityMutationOptions). Deliberate, and it carries a comment saying why the failure is acceptable. Do not reach for this to avoid writing error handling.
Procedure 3: Consume from a component
Import the factories, never the endpoint — and import the
queryClient, never calluseQueryClient():import { queryClient } from "@/query-client"; const credentials = useQuery(credentialListQueryOptions()); const createCredential = useMutation(createCredentialMutationOptions(queryClient));useQueryClient()is not the convention here. There is exactly one client: constructed at module scope inapp/src/query-client.tsand handed to bothQueryClientProviderand the router context inmain.tsx. The hook therefore resolves to the same object the import already holds, at the cost of a hook call and aconstline. The import also works where a hook cannot — a plain event handler, a module with no component around it, a test — which is why mutation factories take aQueryClientparameter rather than reaching for the hook themselves.Import with the
@/alias —@/lib/credentials/queries, not../../../lib/credentials/queries. Both spellings exist in the tree today; the alias is the correct one.Branch on all four states in order, every time — pending, error, empty, rows — and never dereference
datawithout having handled the first three:{credentials.isPending ? null : credentials.error ? ( <p className="text-destructive text-sm" role="alert">Could not load credentials.</p> ) : credentials.data?.length === 0 ? ( <PageEmpty>No credentials are configured.</PageEmpty> ) : ( <PageRows>{/* rows */}</PageRows> )}The pending branch renders nothing. OpenBot has no loading placeholder — no "Loading…" text, no spinner, no skeleton, no shimmer. The section's heading is already on screen; what arrives underneath it is the answer, and a placeholder that appears and vanishes inside a local round-trip is a flicker rather than information. A few screens still carry
<PageEmpty>Loading …</PageEmpty>and one carries aSkeletonblock, both from before this decision. They are not the pattern to copy.isPendingis still branched on, and branched on first. Deleting the branch instead of returningnullfrom it would show the empty-state sentence — "No credentials are configured." — for the whole duration of the fetch, which states something false.This says nothing about mutations. A button the person just pressed still says
"Saving…"or"Deleting…", because that is feedback for an action they took rather than a placeholder for data they are waiting on. Derive it from the mutation, not fromuseState:disabled={... || createCredential.isPending}.Read
credentials.tsxinapp/src/routes/_authed/admin/for the whole pattern end to end — with the caveat that its pending branch still renders text.
Procedure 4: Preload in a route
When data gates navigation, load it in
beforeLoadwithensureQueryDataand the same options factory the component uses:const user = await context.queryClient.ensureQueryData(currentUserQueryOptions()); if (!user) throw redirect({ to: "/sign" });The factory is shared between the guard and the component on purpose — one key, one fetch, and the component's
useQueryis already warm.Authorization decided here, not inside a component (
routes/_authed.tsx,routes/_authed/admin/route.tsx).Inside
beforeLoadandloader, usecontext.queryClient— the router's typed handle, and the same singletonmain.tsxput there. No import needed at those two call sites; everywhere else, import it.
Procedure 5: Test a screen against the spec
- A test that fakes
fetchby hand answers at the API's addresses, in the API's shapes. Each area has a helper that does it (app/tests/bots-api.ts,audit-api.ts,accounts-api.ts,schedules-api.tsand the others): use the area's helper, never a hand-written address. - To prove a screen reads and writes through the generated client, serve it the spec's own mocks:
setupServer(...get<Tag>Mock())from@/lib/api/generated/<tag>/<tag>.msw, with happy-dom given a page address (GlobalRegistrator.register({ url: "http://openbot.invalid/" })) so relative requests resolve.app/tests/bots-generated-client.test.tsxis the reference. - Use
msw2. MSW 3 intercepts at Node's socket layer, which Bun'sfetchdoes not go through, so underbun testits handlers never run. - To prove an entity's reads and writes go only through the generated client, answer at the API's
addresses and refuse every other one, recording each request
(
app/tests/schedules-generated-client.test.ts).
Decision Tree
- Adding or changing an operation the API should offer → Procedure 0 first, then 1 or 2.
- Adding a screen that displays server data → Procedure 1, then Procedure 3.
- Adding a create, update, delete, or toggle → Procedure 2, then Procedure 3.
- The data decides whether the person is allowed on the page at all → Procedure 4.
- Changing an existing payload's shape → Procedure 1, step 2, and check every consumer of the type.
- Filtering or paginating an existing list → Procedure 1, step 5: a new parameter goes in the trailing object of the list key, not into a second key factory.
- The data is form input rather than server state → not this skill;
lib/<entity>/form.ts. - The data arrives over the CopilotKit runtime → not this skill;
lib/copilot/.
Red Flags
| Signal | What it means | Do instead |
|---|---|---|
fetch( anywhere but lib/client.ts |
Either the read has no key and nothing can invalidate it, or the transport has been rewritten by hand | Move it into lib/<entity>/ behind a factory, and call client |
client("/api/agents…") for an operation that is in api/openapi.yaml |
A second, hand-written path to something the generated client already reaches | Call the generated function (getBot, updateBot, …) |
| A hand-written type for a payload the spec describes | Drifts from the contract the first time the spec changes | import type { Bot } from "@/lib/api/generated/model" |
An edit inside app/src/lib/api/generated |
Overwritten by the next api:generate, and CI's drift check fails |
Change the area file under api/openapi/, then bun run api:generate |
A component importing @/lib/api/generated or calling a generated use* hook |
A second cache keyed by URL that no <entity>Keys invalidation reaches |
Call the entity's factory |
A write with no Idempotency-Key, or one built with crypto.randomUUID() |
The spec requires one; randomUUID throws outside a secure context |
{ "Idempotency-Key": idempotencyKey() } |
| A new path whose first name after the organization is one Intelligence serves (threads, memories, projects, learning-…) | Two servers answering one address | Pick another name; api/intelligence-reserved.yaml lists Intelligence's |
A module-private <entity>Request helper |
Superseded. Four of these existed and one had lost its body.error extraction |
Call client |
client on an endpoint whose refusal is an answer |
Turns the boundary working into an exception the caller has to catch | tryClient, and read the status |
body: JSON.stringify(x) at a call site |
Double-encoded; the client serialises | Pass the object |
A one-shot tool call written as a mutationOptions factory |
Gets a queryClient and an invalidation it has no use for |
A plain function beside the factories |
A fallback sentence repeated on every write in a file |
The reader cares which entity failed, and that does not change within a file | One const FALLBACK per file |
<PageEmpty>Loading …</PageEmpty>, a spinner, or a Skeleton while a query is pending |
OpenBot uses no loading placeholder; the flicker costs more than the reassurance buys | Return null from the pending branch |
The pending branch deleted rather than returning null |
The empty-state sentence shows for the length of the fetch, asserting something false | Keep the branch, first in the chain, returning null |
const queryClient = useQueryClient() |
A hook call and a local binding for an object that is one import away, and unavailable outside a component | import { queryClient } from "@/query-client" |
new QueryClient() anywhere outside app/src/query-client.ts |
A second cache; queries written by one client are invisible to the other | Import the singleton. A test needing isolation constructs its own and passes it explicitly |
useQuery({ queryKey: ["agents"], ... }) at a call site |
An inline key drifts from the factory and silently stops matching invalidations | Call the factory: useQuery(agentListQueryOptions()) |
queryClient.setQueryData(...) after a mutation |
Guesses at server-derived fields; wrong the moment the server adds a rule | invalidateQueries({ queryKey: <entity>Keys.all }) |
A component computing user.role === "admin" && thing.ownerId === user.id |
Duplicates an authorization rule that the server already decided | Render the server's flag (canManage, mine) |
A read type carrying a token, key, or plaintext |
Secrets are write-only in OpenBot | Expose hasAuth: boolean or a revokedAt timestamp |
A hand-written body.error extraction |
client already does it, and did it more consistently than the four copies did |
Pass fallback and let it raise |
queryFn returning { agents: [...] } |
Leaks the transport envelope into every component | Unwrap in the queryFn; components see the array |
A second <entity>Keys object, or keys defined in mutations.ts |
Two sources of truth for one cache namespace | One factory per entity, in queries.ts; mutations.ts imports it |
Error Handling
- A 401 in a
queryFn:clientsends the credentials, so a 401 means the session expired — the_authedguard handles the redirect on the next navigation. Do not add per-query redirect logic. The one place a 401 is expected iscurrentUserQueryOptions, which usestryClientbecause not being signed in is an answer there rather than a failure. - The server returns no
errorfield:clientfalls back to thefallbackoption. Name the entity in it ("Learning settings could not be loaded."). Do not print a status code to a person. - A refusal arrives as a thrown
Errorinstead of a value: the call site usedclientwhere it neededtryClient. The gateway declining is the product working, not a fault. - The server rejects a body it should accept, or reads it as a string: something stringified
before handing it over.
clientserialises; a caller passes the object. - An invalidation does not refresh the list: the key at the call site does not match the key the
mutation invalidated. Both must come from the same
<entity>Keysfactory. Check for an inline key array before anything else. - Two filters of the same list overwrite each other's cache: the parameter is missing from the
list key. Add it to the trailing object (
list: (hidden = false) => [..., { hidden }]). - A mutation succeeds but the screen shows stale server-derived fields: something patched the cache instead of invalidating it. Remove the patch.
- TypeScript cannot infer the
queryFnreturn: the explicitPromise<T>annotation is missing from thequeryFnsignature. Add it rather than casting at the call site. - "No X are configured." flashes before the list appears: the pending branch is missing, or it
sits after the empty check. It goes first and returns
null. - A query is slow enough that the blank feels broken: the answer is not a placeholder, it is a slow endpoint. Fix the endpoint, or preload the data in the route (Procedure 4) so the screen is not entered until it is there.
- A mutation factory is needed where no hook can run — a bare event handler, a module with no
component around it, a
bun testfile: importqueryClientfromapp/src/query-client.tsand pass it in. This is the reason the singleton is the convention rather than the hook. - An invalidation appears to do nothing and the keys do match: two clients exist. Search for
new QueryClient(outsideapp/src/query-client.ts. - Unsure which entity directory a new endpoint belongs to: name it after the noun the URL is
about (
/api/agents/:id/pluginsisplugins, keyed by agent). If no existing directory fits, create one with the same three-file shape rather than adding the read to a neighbour.