@vxnsin/inkan 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vensin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,282 @@
-# Temporary Holding Version
+<picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vxnsin/inkan/main/assets/wordmark-dark.svg"><img src="https://raw.githubusercontent.com/vxnsin/inkan/main/assets/wordmark-light.svg" alt="inkan" width="340"></picture>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**An API server for Node where the docs can't lie.**
+
+[![npm](https://img.shields.io/npm/v/@vxnsin/inkan?color=c4381f&labelColor=2b2420&label=npm)](https://www.npmjs.com/package/@vxnsin/inkan)
+[![CI](https://img.shields.io/github/actions/workflow/status/vxnsin/inkan/ci.yml?branch=main&color=3d7a4b&labelColor=2b2420&label=ci)](https://github.com/vxnsin/inkan/actions/workflows/ci.yml)
+[![dependencies](https://img.shields.io/badge/dependencies-0-ece1cf?labelColor=2b2420)](package.json)
+[![License](https://img.shields.io/badge/license-MIT-a87fe0?labelColor=2b2420)](LICENSE)
+[![supports warden](https://raw.githubusercontent.com/vxnsin/warden/main/assets/supports-warden.svg)](https://github.com/vxnsin/warden)
+
+<!-- cozy:cards -->
+<div align="center">
+
+<a href="https://github.com/vxnsin/inkan"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vxnsin/inkan/output/repo-dark.svg?v=e2fea4fc22"><img src="https://raw.githubusercontent.com/vxnsin/inkan/output/repo-light.svg?v=e2fea4fc22" width="840" alt="vxnsin/inkan: An API server for Node where the docs can't lie: one contract per route gives you validation, types, OpenAPI, docs and tests."></picture></a>
+
+<a href="https://github.com/vxnsin/inkan#install"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vxnsin/inkan/output/nav-start-dark.svg?v=c2e08cb92e"><img src="https://raw.githubusercontent.com/vxnsin/inkan/output/nav-start-light.svg?v=c2e08cb92e" width="95" alt="install →"></picture></a><a href="https://www.npmjs.com/package/@vxnsin/inkan"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vxnsin/inkan/output/nav-npm-dark.svg?v=513902168b"><img src="https://raw.githubusercontent.com/vxnsin/inkan/output/nav-npm-light.svg?v=513902168b" width="50" alt="npm"></picture></a><a href="https://github.com/vxnsin/warden"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vxnsin/inkan/output/nav-warden-dark.svg?v=0e950205da"><img src="https://raw.githubusercontent.com/vxnsin/inkan/output/nav-warden-light.svg?v=0e950205da" width="69" alt="warden"></picture></a>
+
+<a href="https://github.com/vxnsin/inkan/commits"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vxnsin/inkan/output/commits-dark.svg?v=5ef5be0d70"><img src="https://raw.githubusercontent.com/vxnsin/inkan/output/commits-light.svg?v=5ef5be0d70" width="840" alt="latest commits of vxnsin/inkan"></picture></a>
+
+<a href="https://github.com/vxnsin/inkan/releases"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vxnsin/inkan/output/releases-dark.svg?v=f1fdb7c523"><img src="https://raw.githubusercontent.com/vxnsin/inkan/output/releases-light.svg?v=f1fdb7c523" width="840" alt="releases: none yet"></picture></a>
+
+<a href="https://github.com/vxnsin/inkan/graphs/contributors"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vxnsin/inkan/output/contributors-dark.svg?v=8bcda569cd"><img src="https://raw.githubusercontent.com/vxnsin/inkan/output/contributors-light.svg?v=8bcda569cd" width="840" alt="contributors: vxnsin"></picture></a>
+
+</div>
+<!-- /cozy:cards -->
+
+An *inkan* (印鑑) is the seal a Japanese contract gets stamped with. Here every
+route carries one: params, query, body, responses and a few examples, written
+once. From that one definition inkan checks what comes in, types your handler,
+checks what goes out, writes OpenAPI 3.1, serves the docs, and runs every
+example as a test.
+
+```ts
+import { inkan, problem, t } from "@vxnsin/inkan";
+
+const Tea = t.object({ id: t.int(), name: t.string(), kind: t.enum(["green", "black", "oolong"]) });
+const teas = [{ id: 1, name: "Sencha", kind: "green" as const }];
+
+const app = inkan({ title: "Tea Shop", version: "1.0.0" });
+
+app.get(
+  "/teas/:id",
+  {
+    params: t.object({ id: t.int() }),
+    response: { 200: Tea, 404: t.problem() },
+    examples: [
+      { name: "found", params: { id: 1 }, expect: { name: "Sencha" } },
+      { name: "missing", params: { id: 99 }, status: 404 },
+    ],
+  },
+  ({ params }) => {
+    const tea = teas.find((x) => x.id === params.id); // params.id is a number, not a string
+    if (!tea) throw problem(404, "tea-not-found", `There is no tea with id ${params.id}`);
+    return tea; // has to be a Tea, or it does not compile
+  },
+);
+
+app.listen();
+```
+
+The examples are what the docs show, and they are what this runs. Say the 404 got lost in a refactor:
+
+```sh
+$ npx inkan check src/app.ts
+
+  印 inkan check  ·  Tea Shop 1.0.0
+
+  GET    /teas/:id
+    ✓ found                              200  0.8ms
+    ✗ missing                            200  0.4ms
+        answered 200, expected 404
+
+  2 examples · 1 sealed · 1 broken
+```
+
+A docs page that is tested is a docs page you can trust. When the handler
+drifts, the check goes red before anyone reads something false.
+
+## Why another one
+
+Express gets out of the way, FastAPI writes your docs. inkan wants both, plus
+the one thing neither does: holding the server to what its docs say.
+
+| | Express | Fastify | FastAPI | inkan |
+| --- | :-: | :-: | :-: | :-: |
+| Handler types come from the schema | – | with a type provider | ✓ | ✓ |
+| OpenAPI document | plugin | plugin | ✓ | ✓ |
+| Docs page | plugin | plugin | ✓ | ✓ no CDN, works offline |
+| Answers trimmed to the contract | – | ✓ | ✓ | ✓ and checked in dev |
+| **Examples run as tests** | – | – | – | ✓ `inkan check` |
+| **Live request inspector** | – | – | – | ✓ `/_inkan` |
+| Every error in one shape ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)) | – | – | – | ✓ |
+| Runtime dependencies | several | several | several | **none** |
+
+## Install
+
+```sh
+npm install @vxnsin/inkan
+```
+
+The package is scoped because npm keeps the plain name `inkan` free of look-alikes. The command it installs is `inkan` either way.
+
+Node 20 or newer. On Node 22.18 and newer, `.ts` files run as they are,
+with no build step and no loader.
+
+## What it does
+
+| | |
+| --- | --- |
+| **Checks what comes in** | `params`, `query`, `headers` and `body` are validated together. Path and query strings become the numbers and booleans the schema asks for. Bad input is one 400 that lists every issue, not just the first. |
+| **Types the handler** | No generics to write. `params.id` is what the schema says, and so is the return value. Without a schema, `:id` in the path is still typed. |
+| **Checks what goes out** | In development, an answer that breaks its contract is a 500 that says where, not a silent surprise for the frontend. Keys the contract does not list are dropped, so a `passwordHash` never leaves by accident. |
+| **Writes OpenAPI 3.1** | At `/openapi.json`, from the same schemas. Named schemas land in `components` once. |
+| **Serves the docs** | At `/docs`. Every example has a send button, and a route gets its seal 印 when all of its examples answer as promised. |
+| **Runs examples as tests** | `inkan check` or `app.check()`, in-process, no port. Routes without examples are listed, so nothing hides. |
+| **Shows what happened** | `/_inkan` is a live log of the last 200 requests and what broke the contract. Development only, loopback only, secret headers hidden. |
+| **Errors in one shape** | `throw problem(404, "tea-not-found", "…")` gives an RFC 9457 document. Every built-in error has the same shape, with a stable `type` to switch on. |
+
+## A route
+
+```ts
+app.post(
+  "/teas",
+  {
+    summary: "Add a tea",
+    tags: ["teas"],
+    body: NewTea,
+    response: { 201: Tea, 409: t.problem() },
+    examples: [
+      { name: "a new oolong", body: { name: "Da Hong Pao", kind: "oolong" }, expect: { id: 2 } },
+      { name: "no name", body: { kind: "green" }, status: 400 },
+    ],
+  },
+  ({ body, reply }) => {
+    const tea = store.add(body);
+    return reply(201, tea, { location: `/teas/${tea.id}` });
+  },
+);
+```
+
+| field | |
+| --- | --- |
+| `params`, `query`, `headers`, `body` | schemas for the input. Header names are lowercase. |
+| `response` | status → schema. The first 2xx is the default status, and no body means 204. |
+| `examples` | `{ name, params, query, headers, body, status, expect }`. `status` defaults to the first 2xx. `expect` is a part of the answer that has to be there. |
+| `summary`, `description`, `tags`, `deprecated`, `operationId` | for the docs |
+| `hidden` | keeps the route out of the docs and OpenAPI |
+| `use` | middleware for this route only, after validation |
+
+A handler returns a value, or `reply(status, body, headers)` for anything
+else. `ctx.reply` is typed to the statuses in the contract, so `reply(418)`
+on a route that never promised a teapot does not compile.
+
+## Schemas
+
+```ts
+t.string().min(1).max(60).email().uuid().pattern(/x/).format("date-time").trim()
+t.int().min(0)   t.number().positive()   t.boolean()
+t.enum(["a", "b"])   t.literal("a")   t.union(t.string(), t.int())
+t.array(Tea).min(1)   t.record(t.int())   t.any()   t.empty()   t.problem()
+t.object({ … }).strict() .passthrough() .pick() .omit() .extend() .partial()
+
+.optional()  .nullable()  .default(v)  .describe("…")  .example(v)  .named("Tea")  .deprecated()
+```
+
+`Infer<typeof Tea>` is the TypeScript type. `Tea.parse(x)` throws a
+`ValidationError`, `Tea.safeParse(x)` does not, and `Tea.toJSONSchema()`
+gives JSON Schema 2020-12.
+
+## Examples are tests
+
+```sh
+npx inkan check src/app.ts            # every route
+npx inkan check src/app.ts --only /teas
+npx inkan check src/app.ts --json     # for CI
+```
+
+The entry file exports the app (`export default app` or `export const app`).
+`app.listen()` stays quiet while the CLI loads it. If the examples change data,
+export a `beforeEach` that puts it back. It runs before every example:
+
+```ts
+export function beforeEach() {
+  store.reset();
+}
+```
+
+Or inside your own tests:
+
+```ts
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { app, beforeEach } from "./app.ts";
+
+test("the contract holds", async () => {
+  const report = await app.check({ beforeEach });
+  assert.equal(report.failed, 0);
+});
+```
+
+For everything the examples do not cover, `app.inject()` sends a request
+straight in, without a socket:
+
+```ts
+const res = await app.inject({ method: "POST", url: "/teas", body: { name: "Gyokuro" } });
+res.status; // 400
+res.body.errors; // [{ in: "body", path: "kind", message: "is required" }, …]
+```
+
+## Middleware and groups
+
+```ts
+app.use(async (ctx, next) => {
+  const started = Date.now();
+  await next();
+  ctx.header("server-timing", `app;dur=${Date.now() - started}`);
+});
+
+const admin = routes().use(requireAdmin).get("/stats", () => stats());
+app.mount("/admin", admin);
+```
+
+`ctx.state` carries things from middleware to the handler. A thrown
+`problem()` stops everything, wherever it is thrown.
+
+## Running it
+
+`app.listen()` takes the port from its argument, then `$PORT`, then 3000. So it
+runs under [warden](https://github.com/vxnsin/warden), a container or a PaaS
+without changes:
+
+```sh
+warden run -- node src/app.ts
+```
+
+On SIGINT or SIGTERM it lets open requests finish (up to ten seconds) before it
+exits. `app.listener` is a plain `(req, res)` function for your own
+`http.createServer`.
+
+```ts
+inkan({
+  title: "Tea Shop", version: "1.0.0", description: "…", servers: [{ url: "https://api.example.com" }],
+  docs: "/docs",                  // or false
+  openapi: "/openapi.json",       // or false
+  inspector: "/_inkan",           // default: on in development, always loopback only
+  validateResponses: true,        // default: on in development
+  bodyLimit: 1024 * 1024,
+  log: true,                      // one line per request, default: on in development
+  gracefulShutdown: true,
+  dev: process.env.NODE_ENV !== "production",
+  onError: (err, ctx) => report(err),
+});
+```
+
+## CLI
+
+```sh
+npx inkan check   src/app.ts [--only <text>] [--json]
+npx inkan openapi src/app.ts [-o openapi.json]
+npx inkan routes  src/app.ts
+```
+
+## Try the example
+
+```sh
+git clone https://github.com/vxnsin/inkan && cd inkan && npm install
+node examples/shop.ts              # then open http://localhost:3000/docs
+node src/cli.ts check examples/shop.ts
+```
+
+## Not yet
+
+- a typed client that reads the routes, with no codegen
+- CORS and `OPTIONS` out of the box
+- streaming answers and file uploads
+- routes from the file tree
+
+Ideas and issues are welcome.
+
+## License
+
+[MIT](LICENSE)

package/assets/logo.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 120" role="img" aria-label="inkan">
+  <defs>
+    <filter id="ink" x="-10%" y="-10%" width="120%" height="120%">
+      <feTurbulence type="fractalNoise" baseFrequency="0.9" numOctaves="2" seed="7" result="noise"/>
+      <feDisplacementMap in="SourceGraphic" in2="noise" scale="2.2"/>
+    </filter>
+  </defs>
+  <g transform="rotate(-4 60 60)" filter="url(#ink)">
+    <rect x="10" y="10" width="100" height="100" rx="22" fill="#c4381f"/>
+    <rect x="20" y="20" width="80" height="80" rx="13" fill="none" stroke="#fbf7ef" stroke-width="3.5"/>
+    <g fill="none" stroke="#fbf7ef" stroke-width="6" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M44 34 C37 34 36 39 36 46 L36 53 C36 57.5 33.5 60 30 60 C33.5 60 36 62.5 36 67 L36 74 C36 81 37 86 44 86"/>
+      <path d="M76 34 C83 34 84 39 84 46 L84 53 C84 57.5 86.5 60 90 60 C86.5 60 84 62.5 84 67 L84 74 C84 81 83 86 76 86"/>
+      <path d="M48.5 61 L56.5 69 L72 51"/>
+    </g>
+  </g>
+</svg>

package/dist/app.d.ts

@@ -0,0 +1,222 @@
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { type Infer, type Schema } from "./schema.ts";
+import { type OpenAPIInfo } from "./openapi.ts";
+import { type CheckOptions, type CheckReport } from "./check.ts";
+export type Responses = {
+    [status: number]: Schema<any>;
+};
+export type Example = {
+    name?: string;
+    params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    body?: unknown;
+    /** The status this example has to answer with. Defaults to the first 2xx in `response`. */
+    status?: number;
+    /** A part of the response body that has to be in the answer, compared deeply. */
+    expect?: unknown;
+};
+export type RouteSpec<P, Q, B, H, R extends Responses> = {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    operationId?: string;
+    deprecated?: boolean;
+    /** Keeps the route out of the docs and the OpenAPI document. */
+    hidden?: boolean;
+    params?: Schema<P>;
+    query?: Schema<Q>;
+    headers?: Schema<H>;
+    body?: Schema<B>;
+    response?: R;
+    examples?: Example[];
+    /** Middleware for this route only. It runs after the input was validated. */
+    use?: Middleware[];
+};
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type ParamsOf<P extends string> = P extends `${string}:${infer Name}/${infer Rest}` ? {
+    [K in Name]: string;
+} & ParamsOf<`/${Rest}`> : P extends `${string}:${infer Name}` ? {
+    [K in Name]: string;
+} : P extends `${string}*${infer W}` ? {
+    [K in W extends "" ? "rest" : W]: string;
+} : {};
+export type PathParams<P extends string> = string extends P ? Record<string, string> : Simplify<ParamsOf<P>>;
+type RawQuery = Record<string, string | string[]>;
+type RawHeaders = Record<string, string | undefined>;
+type SuccessStatus = 200 | 201 | 202 | 203 | 206 | 207;
+type SuccessBody<R> = {} extends R ? unknown : {
+    [K in keyof R]: K extends SuccessStatus ? Infer<R[K]> : never;
+}[keyof R];
+export declare class Reply<S extends number = number, Body = unknown> {
+    status: S;
+    body: Body;
+    headers: Record<string, string>;
+    constructor(status: S, body: Body, headers?: Record<string, string>);
+}
+/** Answers with a status that is not the default one, or with extra headers. */
+export declare const reply: <S extends number, B>(status: S, body?: B, headers?: Record<string, string>) => Reply<S, B | undefined>;
+export type Context<P = Record<string, string>, Q = RawQuery, B = unknown, H = RawHeaders, R extends Responses = {}> = {
+    method: string;
+    path: string;
+    url: URL;
+    params: P;
+    query: Q;
+    headers: H;
+    body: B;
+    /** Free space for middleware to hand things to the handler. */
+    state: Record<string, unknown>;
+    /** The route that matched, as it was written. Undefined before routing. */
+    route?: {
+        method: string;
+        path: string;
+    };
+    /** Sets the status used when the handler returns a plain value. */
+    status(code: number): void;
+    header(name: string, value: string): void;
+    reply<S extends keyof R & number>(status: S, body: Infer<R[S]>, headers?: Record<string, string>): Reply<S>;
+    /** Only there when the request came through a socket, not through `inject`. */
+    req?: IncomingMessage;
+    res?: ServerResponse;
+};
+type Result<R extends Responses> = SuccessBody<R> | Reply | void;
+export type Handler<P, Q, B, H, R extends Responses> = (ctx: Context<P, Q, B, H, R>) => Result<R> | Promise<Result<R>>;
+export type Middleware = (ctx: Context<any, any, any, any, any>, next: () => Promise<void>) => unknown;
+export type RouteRecord = {
+    method: string;
+    path: string;
+    spec: RouteSpec<any, any, any, any, Responses>;
+    handler: Handler<any, any, any, any, any>;
+    use: Middleware[];
+};
+type RouteMethod<Self> = {
+    <Path extends string, P = PathParams<Path>, Q = RawQuery, B = undefined, H = RawHeaders, R extends Responses = {}>(path: Path, spec: RouteSpec<P, Q, B, H, R>, handler: Handler<P, Q, B, H, R>): Self;
+    <Path extends string>(path: Path, handler: Handler<PathParams<Path>, RawQuery, unknown, RawHeaders, {}>): Self;
+};
+/** A set of routes that can be mounted under a prefix. */
+export declare class Routes {
+    /** @internal */
+    _records: RouteRecord[];
+    /** @internal */
+    _use: Middleware[];
+    /** For a group, middleware that every route in it gets. Add it before mounting. */
+    use(...mw: Middleware[]): this;
+    protected define(method: string, path: string, a: unknown, b?: unknown): this;
+    /** @internal */
+    add(r: RouteRecord): void;
+    get: RouteMethod<this>;
+    post: RouteMethod<this>;
+    put: RouteMethod<this>;
+    patch: RouteMethod<this>;
+    delete: RouteMethod<this>;
+    mount(prefix: string, group: Routes): this;
+}
+export declare const routes: () => Routes;
+export type AppOptions = OpenAPIInfo & {
+    /** Where the docs page lives, or false. Default `/docs`. */
+    docs?: string | false;
+    /** Where the OpenAPI document lives, or false. Default `/openapi.json`. */
+    openapi?: string | false;
+    /** The request inspector. On by default in development, and it only answers loopback addresses. */
+    inspector?: string | false;
+    /** Checks what handlers return against `response`. Default: on in development. */
+    validateResponses?: boolean;
+    /** Largest accepted request body in bytes. Default 1 MiB. */
+    bodyLimit?: number;
+    /** One line per request on the console. Default: on in development. */
+    log?: boolean;
+    /** Close in-flight requests cleanly on SIGINT and SIGTERM. Default true. */
+    gracefulShutdown?: boolean;
+    /** Development mode. Default: NODE_ENV is not "production". */
+    dev?: boolean;
+    onError?: (error: unknown, ctx: Context<any, any, any, any, any>) => void;
+};
+export type InjectOptions = {
+    method?: string;
+    url: string;
+    headers?: Record<string, string>;
+    /** Objects are sent as JSON. */
+    body?: unknown;
+};
+export type InjectResponse = {
+    status: number;
+    headers: Record<string, string>;
+    text: string;
+    /** Parsed JSON when the answer was JSON, otherwise the text. */
+    body: any;
+};
+type RawRequest = {
+    method: string;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: Buffer;
+    remote?: string;
+    req?: IncomingMessage;
+    res?: ServerResponse;
+};
+type RawResponse = {
+    status: number;
+    headers: Record<string, string>;
+    body?: string | Buffer;
+};
+export type LogEntry = {
+    id: number;
+    at: string;
+    method: string;
+    path: string;
+    route?: string;
+    status: number;
+    ms: number;
+    notes: string[];
+    request: {
+        headers: Record<string, string>;
+        body?: string;
+    };
+    response: {
+        body?: string;
+    };
+};
+export declare class App extends Routes {
+    options: AppOptions;
+    dev: boolean;
+    private router;
+    private global;
+    private log;
+    private logId;
+    private spec?;
+    constructor(options?: AppOptions);
+    /** Middleware for every request, before routing. */
+    use(...mw: Middleware[]): this;
+    /** @internal */
+    add(r: RouteRecord): void;
+    routes(): RouteRecord[];
+    openapi(): Record<string, unknown>;
+    /** Runs every route's examples against the app, without a socket. */
+    check(opts?: CheckOptions): Promise<CheckReport>;
+    /** Sends a request straight into the app. Good for tests: no port, no network. */
+    inject(opts: InjectOptions): Promise<InjectResponse>;
+    /** @internal */
+    handle(raw: RawRequest): Promise<RawResponse>;
+    private respond;
+    private fail;
+    private builtin;
+    private remember;
+    /** A plain Node request listener, for `http.createServer` or anything that takes one. */
+    get listener(): (req: IncomingMessage, res: ServerResponse) => undefined;
+    private serve;
+    /**
+     * Starts listening. The port comes from the argument, then $PORT, then 3000,
+     * so it runs under warden, a PaaS or a container without changes.
+     */
+    listen(port?: number, host?: string): Promise<Server>;
+    private banner;
+}
+export declare const inkan: (options?: AppOptions) => App;
+/**
+ * The schema a status answers with. A route that takes input also promises
+ * a 400 problem for input that breaks the contract, without saying so.
+ */
+export declare function contractFor(route: RouteRecord, status: number): Schema<any> | undefined;
+export {};