@plurid/uitive-server
On this page
The Fetch-standard handler that serves the model planner, with its limits and streaming. It re-exports the planner.
Install: pnpm add @plurid/uitive-server, with zod ^4.2.0 as a peer. Guides: Planning.
- The handler:
createUitiveHandler,HandlerOptions @plurid/uitive-server/node:toNodeListener,FetchHandler,NodeListener,NodeListenerOptions,NodeRequest- Re-exported
The handler
Source: handler.ts
createUitiveHandler
A Fetch-standard handler: POST …/plan and POST …/command take a plan request as JSON and
answer with a plan result. It owns the contract (clients send only its hash), refuses cross-site
requests, checks every request's shape before a planner sees it, never logs bodies, and tells
the browser only what failed, never a provider's details. Clients that accept
application/x-ndjson get progress lines, then the result or an error.
function createUitiveHandler(options: HandlerOptions): (request: Request) => Promise<Response>;Uses: HandlerOptions.
HandlerOptions
What createUitiveHandler takes: the contract it serves, who plans, who may ask, and its
limits.
Uses: AnyContract, Planner.
| Property | Type | Default | Description |
|---|---|---|---|
contract | AnyContract | The contract the application's clients use; requests made with another are refused with 409. | |
planner | Planner | Who plans, such as modelPlanner({ model }), with the server's own key. | |
authorize() | (request: Request) => boolean | Promise<boolean> | Whether a request may plan: the application's own check of the person's session, the one its API makes. Planning spends money, so there is no default. Until the application has one, allowing requests only outside production (process.env.NODE_ENV !== 'production') keeps local development working and refuses everyone once deployed. | |
maxBody? | number | 131072 | Largest request body in bytes. |
perMinute? | number | 20 | Requests per minute per client, as client tells them apart. |
client?() | (request: Request) => string | the right-most X-Forwarded-For entry, which the proxy in front of the server wrote, else 'local', one budget for every request | Tells clients apart for perMinute. Behind more than one proxy, return the address your own proxy recorded. |
onError?() | (error: unknown) => void | logs the message to the console | Told about failures; never sees request bodies. |
@plurid/uitive-server/node
Source: node.ts
toNodeListener
Serves a Fetch-standard handler from Node's (request, response) listeners: Express, Fastify's
raw routes and node:http alike, in CommonJS or ES modules. A body that middleware such as
express.json() already parsed is used as it is. Responses stream, so progress lines arrive as
they are written, and a request the client abandons is aborted. The request keeps its path and
query under a fixed origin, since its Host header proves nothing. The listener never rejects:
a request it can't read is answered 400, and a handler that throws, 500.
app.use('/api/uitive', toNodeListener(handler));function toNodeListener(handler: FetchHandler, options?: NodeListenerOptions): NodeListener;Import from @plurid/uitive-server/node.
Uses: FetchHandler, NodeListener, NodeListenerOptions.
FetchHandler
A Fetch-standard handler, such as createUitiveHandler returns.
type FetchHandler = (request: Request) => Promise<Response>;Import from @plurid/uitive-server/node.
NodeListener
A Node (request, response) listener, as node:http and Express take one.
type NodeListener = (request: NodeRequest, response: ServerResponse) => Promise<void>;Import from @plurid/uitive-server/node.
Uses: NodeRequest.
NodeListenerOptions
How toNodeListener reads requests, and whom it tells when the handler fails.
Import from @plurid/uitive-server/node.
| Property | Type | Default | Description |
|---|---|---|---|
maxBody? | number | 131072, the handler's default | Largest request body read, in bytes; larger ones are refused unread. It is checked before the handler's own maxBody, so raise both together. |
onError?() | (error: unknown) => void | logs the message to the console | Told when the handler throws or its response breaks off; never sees request bodies. |
NodeRequest
Node's request, with what Express and similar frameworks may add to it.
type NodeRequest = IncomingMessage & {
originalUrl?: string;
body?: unknown;
};Import from @plurid/uitive-server/node.
Re-exported
From @plurid/uitive-planner: anthropic, contractText, costOf, DEFAULT_MODELS, environmentModel, google, limits, modelPlanner, offeredBlocks, openai, outputSchema, PlannerError, planRequestSchema, repairText, requestText, RULES, size, toOperations, vocabulary, AnthropicOptions, GoogleOptions, Model, ModelCall, ModelMessage, ModelPlannerOptions, ModelPrices, ModelReply, ModelUsage, OpenAIOptions, PlannerOutput, SchemaOptions, Vocabulary.