Server API#

Everything importable from @janux/server.

api(def)#

export const pay = api({
  description: 'Charge the cart. Irreversible.',
  input: schema({ total: money() }),
  output: schema({ orderId: str() }),   // validated after run (dev safety net)
  guard: 'confirm',
  run: ({ input, ctx }) => payments.charge(input.total, ctx.userId),
});

The returned value is directly callable on the server (await pay({ total: 100 })) — SSR sources and other apis use it without HTTP. Client bundles swap the whole *.api.ts module for fetch stubs at build time (SWC).

Conventions: files live in src/server/<module>.api.ts; tool names become api.<module>.<export>. Only export const x = api({...}) is supported — export default, export function and re-exports fail the build loudly. Names may not contain __.

createJanuxServer(options)#

Returns { fetch(req): Promise<Response>, apiTools, manifestFor } — mount fetch on Bun.serve, or anything Request/Response-shaped.

Route modules#

export const meta = { title: 'Shop', description: '...' };          // or a function:
export const meta = ({ params }) => ({ title: `Order ${params.id}` });

export const staticParams = [{ id: '1' }, { id: '2' }];             // or a function (async supported):
export const staticParams = () => orders.map(({ id }) => ({ id }));

export default async function Page({ ctx, params }) { ... }         // async supported

routes/index.tsx → / · routes/orders/[id].tsx → /orders/:id (params decoded).

staticParams enumerates the concrete pages of a dynamic route: llms.txt lists /orders/1, /orders/2 instead of the raw /orders/[id] pattern, and with output: "static" they become the prerendered pages. Without it, the pattern is listed as-is (and the route is skipped in static builds). See Deploying → Static export.

The document head (PageMeta)#

meta returns a PageMeta. title and description fall back to the app config; everything else is per-page:

import type { PageMeta } from 'janux';

export function meta({ params }): PageMeta {
  return {
    title: 'What is Janux? — Janux docs',
    description: 'The agent-native fullstack UI framework.',
    image: '/og/what-is-janux.png',   // og:image + twitter:image
    canonical: `/docs/${params.section}/${params.slug}`,
    robots: 'index,follow',
    jsonLd: { '@context': 'https://schema.org', '@type': 'TechArticle', headline: 'What is Janux?' },
  };
}

og:* and twitter:* are derived from title, description, image and canonical, so a page that sets those four already has a correct social card; you only reach for og/twitter to override.

image and canonical may be root-relative — Open Graph requires absolute URLs, so the shell resolves them against siteUrl. Without a siteUrl a relative value is dropped rather than emitted broken, with a warning.

The escape hatch covers the rest — a preload hint, an alternate link, a domain verification tag:

head: [{ tag: 'link', attrs: { rel: 'preload', as: 'image', href: '/demo-poster.jpg' } }];

Every head node the shell writes carries a stable id (jx-og-title, jx-jsonld-0, jx-head-0, …). That is what lets SPA navigation match them by identity across the document diff: leaving a page drops its social tags instead of stranding the previous page's card, and a tag both pages declare is updated in place.

HTTP surface#

Error envelope: { ok: false, error } with 400 (invalid input), 401 (agent_required), 403 (forbidden), 404, 500.

Client navigations announce themselves#

A page fetched by the client runtime during an SPA navigation carries x-janux-navigation: 1 (NAVIGATION_HEADER). The server answers those without the inlined stylesheet: the live document already has it, the client keeps its <style> nodes across the diff, and re-sending it puts kilobytes in front of the content the visitor is waiting for — 27 KB of this site's 95 KB page.

import { NAVIGATION_HEADER } from '@janux/server';

// Two different responses share one URL, so anything caching them must vary on it.
const vary = NAVIGATION_HEADER;

If you cache pages at the edge, vary on that header — a navigation response and a first-load response are not interchangeable.

Verified agent identity (Web Bot Auth)#

External agents can sign requests per RFC 9421 / Web Bot Auth (Ed25519 HTTP message signatures). Configure an allowlist of agent public JWKs:

createJanuxServer({
  agents: {
    webBotAuth: { keys: [agentPublicJwk] },
    policy: 'observe',   // default: identify agents, serve everyone
  },
});

Signed requests get ctx.agent = { verified, keyId } (also null/absent when unsigned); use it in ctxFor-style authorization, guards or run(). Under policy: 'require', unsigned or unverified requests with x-janux-origin: agent receive 401 { error: 'agent_required' } — human traffic is never gated, and neither is the embedded copilot (/_janux/agent): it acts on the signed-in user's own session, so its authentication belongs in ctxFor like any human traffic. Fail closed: unknown key, bad signature, expired window, or require with an empty allowlist all deny.

Not built yet: fetching keys from a signature-agent directory (SSRF story needed), nonce single-use enforcement, rate limiting (put it in ctxFor or your middleware — onAudit gives you per-tool outcome data to alert on).

Low-level exports (advanced)#

createJanuxServer composes these; import them directly only to embed Janux in another server or to test pieces in isolation.