Client

okengine/client is how a browser, CLI, or another service calls your app's flows. Adopt the unit, take typeof app, and api.notes.get({ id }) is fully typed — same contracts the server already has, no separate schema project.

Quick start

import { oke } from "okengine";
import * as main from "./flows/main";

export const app = oke({ name: "standard" }).adopt({ main });
export type App = typeof app;

import { createClient } from "okengine/client";
import { app } from "./app";

const api = createClient(app, "http://localhost:6530");

const { data, error } = await api.main.health();

if (error) {
  // TransportError or a declared flow code
  return;
}

// data inferred from the flow's `out`
console.log(data.ok);

createClient forms

oke dev regenerates oke-client.d.ts from GET /_oke/client.json. A separate frontend repo runs oke client add <url> (default out: oke-client.d.ts).

oke client add http://localhost:6530
oke client add https://api.example.com --out ./types/oke-client.d.ts

Options

Consequence: createClient<App>(url) alone types the proxy but still posts POST /_oke/{unit}/{flow} until you pass the app value, $routes, or routes.

REST vs RPC

// REST — createClient(app, url) saw method/path from on(http.get("/notes/:id"), …)
await api.notes.get({ id: "n_1" }); // GET /notes/n_1

// RPC — untriggered flow named notes.stats
await api.notes.stats({ id: "n_1" }); // POST /_oke/notes/stats

Result envelope and helpers

Success may include optional top-level meta (for example pagination). Declared flow errors and transport failures share the failure arm:

import { isOk, isFail, isErrorCode, isTransportError } from "okengine/client";

const result = await api.bookings.create({ flightId: "SK1", seats: 9 });

if (isOk(result)) {
  result.data.id;
} else if (result.error.code === "FlightFull") {
  result.error.data.seatsLeft; // narrowed
} else if (isTransportError(result.error)) {
  result.error.data.message;
}

isFail(result); // true when error !== null
isErrorCode(result.error, "FlightFull"); // type predicate helper

Prefer error?.code === "FlightFull" for inference; use isErrorCode in shared helpers.

Auth on the client

One client: createClient. With gate.auth, the app exposes /auth/* Flows (sign-in, refresh, me). Helpers under okengine/client/auth store tokens — they are not a second factory.

import { createClient } from "okengine/client";
import { memorySession } from "okengine/client/auth";
import { app } from "./app";

const session = memorySession();

const api = createClient(app, "http://localhost:6530", {
  auth: {
    getToken: () => session.getToken(),
    refresh: () => session.refresh(api),
  },
});

const { data } = await api.auth.signInEmail({ email, password });
if (data) session.set(data);

React: useSession(api, session) from okengine/client-react.

Consequence: refresh must mutate whatever getToken reads. Returning a new string alone does nothing if storage was not updated.

After a gated call, switch on the denial codes (values, not throws):

These gate codes are not listed in each Flow’s errors map — they can appear on any gated route.

A 401 with no { data, error } body becomes TransportError with data.status: 401.

Core okengine/client stays under the size budget — helpers are separate exports. Not in core today: cookie jars or plugin .client() decorations. Browser apps: also see CORS and CSRF.

Elements from the client

Store resources

Mount a resource, adopt the returned ops, then call the five Flows like any other:

const notesR = store.resource(db, notes, {/* in, out, list, unit: "notes" */});
const mounted = on(http.resource("/notes", notesR.all()));
// .adopt({ notes: mounted }) →
await api.notes.list({ limit: 20 }); // GET /notes?limit=20 — meta may carry nextCursor
await api.notes.get({ id }); // GET /notes/:id — NotFound when missing
await api.notes.remove({ id }); // DELETE → 204, data undefined

See Store for the list query language and schemas. Auth posture for HTTP triggers is covered under Gate.

Signal and live queries

delivery: "live" and http.get(…).live() are Manifest / driver flags today. okengine/client does not expose WebSocket, SSE, or api.*.subscribe. Until that ships, poll or call an HTTP Flow that returns the current state.

Exports

Budget: the ./client export stays under the measured client-runtime cap (hard gate in CI).

Troubleshooting

Learn more

• Basic usage — adopt → client → test loop
• Gate — policies, gate.public, denials
• Store — store.resource and list query language
• Flow — in / out / errors and fx.fail
• Errors — framework codes vs failure values
• CORS · CSRF — browser callers
• CLI Reference — oke client add, oke dev

Next