# @askrjs/server/askr

> Published API exports for @askrjs/server/askr.

Source: [https://askrjs.com/docs/reference/api/server/askr](https://askrjs.com/docs/reference/api/server/askr)

Status: stable. Packages: @askrjs/server/askr.

**Published packages are authoritative.** Examples may lag behind a published contract. When guidance differs, verify the exports and TypeScript declarations in your installed package, then file an issue.

## Exports

This entrypoint publishes 21 exports from the declarations shipped by @askrjs/server.

### `ActionCookieInstruction`

```ts
ActionCookieInstruction: {
  readonly name: string;
  readonly value: string;
  readonly clear?: false;
  readonly options?: CookieOptions;
} | {
  readonly name: string;
  readonly clear: true;
  readonly value?: never;
  readonly options?: CookieOptions;
}
```

A cookie to set or clear as part of an {@link ActionOutcome}.

### `ActionEntry`

```ts
ActionEntry: any
```

A registered action: its descriptor (schema/id) paired with its handler, as produced by {@link handleAction }.

- `descriptor`: readonly descriptor: ActionDescriptor<Input>;

- `handler`: readonly handler: ActionHandler<Dependencies, Input, Result>;

### `ActionExecution`

```ts
ActionExecution: {
  readonly kind: "response";
  readonly response: Response;
} | {
  readonly kind: "invalid";
  readonly action: string;
  readonly values: Readonly<Record<string, unknown>>;
  readonly issues: readonly Issue[];
  readonly fieldErrors: Readonly<Record<string, readonly string[]>>;
}
```

Result of {@link ActionRegistry.execute}: either a final response, or invalid-input details to re-render the page with.

### `ActionExecutionOptions`

```ts
ActionExecutionOptions: any
```

Options passed to {@link ActionRegistry.execute} describing the current page's allowed actions.

- `authorized`: readonly authorized: readonly ActionDescriptor[];

- `params`: readonly params: Params;

- `policies`: readonly policies: readonly RoutePolicy[];

- `allowsRedirect`: readonly allowsRedirect: (location: URL) => boolean;

### `ActionHandler`

```ts
ActionHandler: (context: ActionHandlerContext, input: Input, dependencies: Dependencies) => ActionOutcome<Result> | Promise<ActionOutcome<Result>>
```

A server action's business logic: validated `input` in, an {@link ActionOutcome} out.

### `ActionHandlerContext`

```ts
ActionHandlerContext: any
```

Request-derived context passed to an {@link ActionHandler}.

- `request`: readonly request: Request;

- `url`: readonly url: URL;

- `params`: readonly params: Params;

- `auth`: readonly auth: AuthContext;

- `policies`: readonly policies: readonly RoutePolicy[];

- `signal`: readonly signal: AbortSignal;

### `ActionOutcome`

```ts
ActionOutcome: any
```

The result of a successful {@link ActionHandler} invocation: an optional redirect, result payload, and cookies.

- `redirect`: readonly redirect?: string;

- `result`: readonly result?: Result;

- `cookies`: readonly cookies?: readonly ActionCookieInstruction[];

### `ActionRegistration`

```ts
ActionRegistration: any
```

A type-erased {@link ActionEntry}, as accepted by {@link defineServerActions }.

- `descriptor`: readonly descriptor: ActionDescriptor;

- `handler`: readonly handler: (context: ActionHandlerContext, input: never, dependencies: Dependencies) => ActionOutcome<unknown> | Promise<ActionOutcome<unknown>>;

### `ActionRegistry`

```ts
ActionRegistry: any
```

A registry of server actions, as created by {@link defineServerActions }, used by {@link createAskrPageHandler }.

- `entries`: readonly entries: readonly Readonly<{
    descriptor: ActionDescriptor;
  }>[];

- `csrfToken`: csrfToken(context: ServerContext): Promise<string | undefined>;

- `execute`: execute(context: ServerContext, options: ActionExecutionOptions): Promise<ActionExecution | undefined>;

### `ActionRegistryOptions`

```ts
ActionRegistryOptions: any
```

CSRF configuration shared by {@link ServerActionsOptions }.

- `csrf`: Page actions are protected by session-bound CSRF by default.

The default identity is `context.auth.session?.id`, so anonymous pages do
not receive a token and their submissions are rejected. Pre-authentication
forms such as login, signup, and password reset must establish an opaque
guest session before rendering and return its stable identity from
`sessionId`. The resolver identifies an existing session; it does not
create or persist one.

Set this to `false` only when the complete flow intentionally uses another
CSRF defense.

- `randomSecret`: readonly randomSecret?: () => string;

### `AskrApp`

```ts
AskrApp: any
```

A configured Askr application, as returned by {@link createAskrApp}.

- `fetch`: fetch(request: Request): Promise<Response>;

- `toOpenApiDocument`: toOpenApiDocument(): OpenApiDocument;

- `close`: close(): Promise<void>;

### `AskrAppApi`

```ts
AskrAppApi: any
```

The API group passed to {@link AskrAppApiOptions.define}, extended with a `schema` helper.

- `schema`: schema: ApiDefinition<Dependencies>["schema"];

### `AskrAppApiOptions`

```ts
AskrAppApiOptions: any
```

Options for the OpenAPI-backed API portion of an {@link AskrApp}.

- `prefix`: readonly prefix?: string;

- `securitySchemes`: readonly securitySchemes?: Readonly<Record<string, SecurityScheme>>;

- `define`: readonly define?: (api: AskrAppApi<Dependencies>) => void;

- `validateResponses`: readonly validateResponses?: boolean;

### `AskrAppAuthOptions`

```ts
AskrAppAuthOptions: any
```

Authentication configuration for an {@link AskrApp}: request resolver, optional auth routes, and page auth policy.

- `resolver`: readonly resolver: AuthResolver;

- `routes`: readonly routes?: AuthRouteOptions<P>;

- `pages`: readonly pages?: RouteAuthOptions;

### `AskrAppOptions`

```ts
AskrAppOptions: any
```

Options for {@link createAskrApp}.

- `name`: readonly name: string;

- `version`: readonly version: string;

- `dependencies`: readonly dependencies: Dependencies;

- `pages`: readonly pages: RouteRegistry;

- `queryRegistry`: readonly queryRegistry?: ServerQueryRegistry;

- `api`: readonly api?: AskrAppApiOptions<Dependencies>;

- `actions`: readonly actions?: ActionRegistryOptions & {
    readonly handlers: readonly ActionRegistration<Dependencies>[];
  };

- `auth`: readonly auth?: AskrAppAuthOptions<P>;

- `middleware`: readonly middleware?: readonly Middleware[];

- `probes`: readonly probes?: ProbeOptions;

- `telemetry`: readonly telemetry?: ServerTelemetry;

- `onError`: readonly onError?: ServerAppOptions["onError"];

- `onAccessDenied`: readonly onAccessDenied?: ServerAppOptions["onAccessDenied"];

- `close`: readonly close?: (dependencies: Dependencies) => void | Promise<void>;

- `cspNonce`: readonly cspNonce?: CspNonceProvider;

### `AskrPageHandlerOptions`

```ts
AskrPageHandlerOptions: any
```

Options for {@link createAskrPageHandler}.

- `registry`: registry: RouteRegistry;

- `auth`: auth?: RouteAuthOptions;

- `queryRegistry`: queryRegistry?: ServerQueryRegistry;

- `seed`: seed?: number;

- `actions`: actions?: ActionRegistry;

- `cspNonce`: cspNonce?: CspNonceProvider;

### `createAskrApp`

```ts
createAskrApp: <Dependencies, P extends Principal = Principal>(options: AskrAppOptions<Dependencies, P>) => AskrApp
```

Assembles a complete Askr application from page routes, an optional OpenAPI-described API,
optional server actions, and optional authentication — wiring an API router (mounted at
`options.api?.prefix`, default `/api`), auth routes, and a page-rendering fallback handler
into a single {@link ServerApp }-like object.

### `createAskrPageHandler`

```ts
createAskrPageHandler: (options: AskrPageHandlerOptions) => Handler
```

Creates a catch-all route {@link Handler} that server-renders Askr framework pages: routes
`GET`/`HEAD` requests through Askr's SSR pipeline, and (if `options.actions` is provided)
dispatches `POST` requests as form actions, re-rendering the page with validation errors on
failure or following a redirect/response on success.

### `defineServerActions`

```ts
defineServerActions: <Dependencies>(options: ServerActionsOptions<Dependencies>, ...entries: readonly ActionRegistration<Dependencies>[]) => ActionRegistry
```

Builds an {@link ActionRegistry} from a set of {@link ActionEntry}s (via {@link handleAction}),
wiring up CSRF token issuance/verification (unless `options.csrf` is `false`), submission
parsing (JSON or form-encoded), input validation, telemetry, and response negotiation
(redirect vs. JSON envelope) for each action invocation.

### `handleAction`

```ts
handleAction: <Dependencies, Input extends Record<string, unknown>, Result = unknown>(descriptor: ActionDescriptor<Input>, handler: ActionHandler<Dependencies, Input, Result>) => ActionEntry<Dependencies, Input, Result>
```

Pairs an action descriptor (its ID and input schema) with a typed handler, ready to pass to
{@link defineServerActions}.

### `ServerActionsOptions`

```ts
ServerActionsOptions: any
```

Options for {@link defineServerActions }.

- `dependencies`: readonly dependencies: Dependencies;

## Documentation navigation

[Previous](https://askrjs.com/docs/reference/api/server/middleware/index.md) | [Next](https://askrjs.com/docs/reference/api/server/auth/index.md)