# @plurid/uitive-server

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](https://uitive.dev/docs/planning).

- [The handler](https://uitive.dev/docs/api/server#the-handler): [`createUitiveHandler`](https://uitive.dev/docs/api/server#createuitivehandler), [`HandlerOptions`](https://uitive.dev/docs/api/server#handleroptions)
- [`@plurid/uitive-server/node`](https://uitive.dev/docs/api/server#pluriduitive-servernode): [`toNodeListener`](https://uitive.dev/docs/api/server#tonodelistener), [`FetchHandler`](https://uitive.dev/docs/api/server#fetchhandler), [`NodeListener`](https://uitive.dev/docs/api/server#nodelistener), [`NodeListenerOptions`](https://uitive.dev/docs/api/server#nodelisteneroptions), [`NodeRequest`](https://uitive.dev/docs/api/server#noderequest)
- [Re-exported](https://uitive.dev/docs/api/server#re-exported)

## The handler

Source: [`handler.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/server/src/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.

```ts
function createUitiveHandler(options: HandlerOptions): (request: Request) => Promise<Response>;
```

Uses: [`HandlerOptions`](https://uitive.dev/docs/api/server#handleroptions).

### HandlerOptions

What `createUitiveHandler` takes: the contract it serves, who plans, who may ask, and its
limits.

Uses: [`AnyContract`](https://uitive.dev/docs/api/core#anycontract), [`Planner`](https://uitive.dev/docs/api/core#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`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/server/src/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.

```ts
app.use('/api/uitive', toNodeListener(handler));
```

```ts
function toNodeListener(handler: FetchHandler, options?: NodeListenerOptions): NodeListener;
```

Import from `@plurid/uitive-server/node`.

Uses: [`FetchHandler`](https://uitive.dev/docs/api/server#fetchhandler), [`NodeListener`](https://uitive.dev/docs/api/server#nodelistener), [`NodeListenerOptions`](https://uitive.dev/docs/api/server#nodelisteneroptions).

### FetchHandler

A Fetch-standard handler, such as `createUitiveHandler` returns.

```ts
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.

```ts
type NodeListener = (request: NodeRequest, response: ServerResponse) => Promise<void>;
```

Import from `@plurid/uitive-server/node`.

Uses: [`NodeRequest`](https://uitive.dev/docs/api/server#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.

```ts
type NodeRequest = IncomingMessage & {
  originalUrl?: string;
  body?: unknown;
};
```

Import from `@plurid/uitive-server/node`.

## Re-exported

From [`@plurid/uitive-planner`](https://uitive.dev/docs/api/planner): [`anthropic`](https://uitive.dev/docs/api/planner#anthropic), [`contractText`](https://uitive.dev/docs/api/planner#contracttext), [`costOf`](https://uitive.dev/docs/api/planner#costof), [`DEFAULT_MODELS`](https://uitive.dev/docs/api/planner#default_models), [`environmentModel`](https://uitive.dev/docs/api/planner#environmentmodel), [`google`](https://uitive.dev/docs/api/planner#google), [`limits`](https://uitive.dev/docs/api/planner#limits), [`modelPlanner`](https://uitive.dev/docs/api/planner#modelplanner), [`offeredBlocks`](https://uitive.dev/docs/api/planner#offeredblocks), [`openai`](https://uitive.dev/docs/api/planner#openai), [`outputSchema`](https://uitive.dev/docs/api/planner#outputschema), [`PlannerError`](https://uitive.dev/docs/api/planner#plannererror), [`planRequestSchema`](https://uitive.dev/docs/api/planner#planrequestschema), [`repairText`](https://uitive.dev/docs/api/planner#repairtext), [`requestText`](https://uitive.dev/docs/api/planner#requesttext), [`RULES`](https://uitive.dev/docs/api/planner#rules), [`size`](https://uitive.dev/docs/api/planner#size), [`toOperations`](https://uitive.dev/docs/api/planner#tooperations), [`vocabulary`](https://uitive.dev/docs/api/planner#vocabulary), [`AnthropicOptions`](https://uitive.dev/docs/api/planner#anthropicoptions), [`GoogleOptions`](https://uitive.dev/docs/api/planner#googleoptions), [`Model`](https://uitive.dev/docs/api/planner#model), [`ModelCall`](https://uitive.dev/docs/api/planner#modelcall), [`ModelMessage`](https://uitive.dev/docs/api/planner#modelmessage), [`ModelPlannerOptions`](https://uitive.dev/docs/api/planner#modelplanneroptions), [`ModelPrices`](https://uitive.dev/docs/api/planner#modelprices), [`ModelReply`](https://uitive.dev/docs/api/planner#modelreply), [`ModelUsage`](https://uitive.dev/docs/api/planner#modelusage), [`OpenAIOptions`](https://uitive.dev/docs/api/planner#openaioptions), [`PlannerOutput`](https://uitive.dev/docs/api/planner#planneroutput), [`SchemaOptions`](https://uitive.dev/docs/api/planner#schemaoptions), [`Vocabulary`](https://uitive.dev/docs/api/planner#vocabulary-type).
