@wolfstar/plugin-api

npm install @wolfstar/plugin-api

pnpm add @wolfstar/plugin-api

yarn add @wolfstar/plugin-api

bun add @wolfstar/plugin-api

npm

Source

See the Plugins guide for how plugins from wolfstar-project/plugins fit alongside the core framework.

Description

A plugin for @wolfstar/http-framework, ported from @sapphire/plugin-api 8.3.1. It exposes a standalone REST API server for health checks, dashboards, or webhooks from other services. It is built on the same @sapphire/pieces Route/Middleware conventions. The plugin is intentionally independent from Client#server (the interactions webhook). That server already claims every path on its port and answers 404 for anything that doesn’t match. This plugin binds its own Server on a separate port instead of sharing the same listener.

Version 2.0.0 matches @sapphire/plugin-api 8.3.1 except for authentication, and renames most exports. If you are upgrading, see Migrating from 1.x.

Installation

pnpm add @wolfstar/plugin-api

Requires Node.js >=22.0.0 and @wolfstar/http-framework ^3.6.0 || ^5.0.0 || ^6.0.0.

Usage

Import the side-effecting register entrypoint before you create your Client:

import '@wolfstar/plugin-api/register';
import { Client } from '@wolfstar/http-framework';

const client = new Client({
	api: {
		prefix: 'v1',
		listenOptions: { port: 4000 },
		origin: '*'
	}
});

await client.load();
await client.listen({ port: 8080 }); // interactions webhook; the API server starts right after

Activating with `modules`

On framework 6.1 and later, list the ./module entry in modules in stars.config instead of importing register. It needs the optional @wolfstar/kit peer dependency, at ^0.2.0 || ^0.3.0.

// stars.config.ts
import { defineConfig } from '@wolfstar/http-framework/config';
import '@wolfstar/plugin-api/module';

export default defineConfig({
	modules: ['@wolfstar/plugin-api/module'],
	api: { prefix: 'v1', listenOptions: { port: 4000 } }
});

The module reads its options from the api key of stars.config. The [specifier, options] tuple of modules still works. Its options are merged over the api key, so they win. The optional @wolfstar/schema peer dependency types the api key in defineConfig. TypeScript only loads that type once the module is imported, so import @wolfstar/plugin-api/module in stars.config.ts. Module options must be JSON-serialisable. Set anything else, such as server options holding functions, through ClientOptions.api, which is merged over the module options. Without the stars CLI, pass the ./plugin definePlugin factory to the plugins client option:

import apiPlugin from '@wolfstar/plugin-api/plugin';

const client = new Client({
	plugins: [apiPlugin({ prefix: 'v1', listenOptions: { port: 4000 } })]
});

Use only one of the module, the ./plugin factory, and register. Combining them installs the plugin’s hooks twice. container.server is the running Server. It is an AsyncEventEmitter (see Events). The package also exports version, a string with the installed @wolfstar/plugin-api version:

import { version } from '@wolfstar/plugin-api';

console.log(`plugin-api v${version}`);

Writing a route

Routes are Route pieces loaded from a routes directory, exactly like commands/listeners:

// src/routes/health.get.ts
import { Route } from '@wolfstar/plugin-api';

export class HealthRoute extends Route {
	public run(_request: Route.Request, response: Route.Response) {
		response.json({ status: 'ok' });
	}
}

The route’s path and method are inferred from its location. src/routes/health.get.ts registers GET /health, and a file named index maps to its directory. A folder named [id] becomes a dynamic segment (request.params.id), and a (group)-style folder is skipped when building the path. You can override the path, methods, and body limit explicitly:

import { Route } from '@wolfstar/plugin-api';

export class HealthRoute extends Route {
	public constructor(context: Route.LoaderContext) {
		super(context, {
			route: '/status',
			methods: ['GET', 'HEAD'],
			maximumBodyLength: 1024 // overrides ServerOptions.maximumBodyLength for this route
		});
	}

	public run(request: Route.Request, response: Route.Response) {
		response.json({ status: 'ok', method: request.method });
	}
}

ServerOptions.prefix is prepended to every route path, so with prefix: 'v1' the route above answers GET /v1/status. Params are percent-decoded. A malformed sequence (for example %E0%A4%A) falls back to the raw value instead of failing the request.

A route declared with no methods matches nothing, and its path answers 404. There is no implicit GET. A route whose file name has no method suffix and that passes no methods option is never reachable. Name the file health.get.ts or pass methods.

Reading the request

ApiRequest (Route.Request) extends IncomingMessage:

Member	Description
`query`	Parsed query string, `Record<string, string \| string[]>`.
`params`	Dynamic segments of the matched route.
`route`, `routerNode`	The matched `Route` / `RouterNode` (`null` when nothing matched).
`readBody()`	Parses the body according to its `Content-Type`.
`readBodyJson()`, `readBodyText()`, `readBodyFormData()`	Typed readers (JSON, text, `application/x-www-form-urlencoded`/multipart).
`readBodyArrayBuffer()`, `readBodyBlob()`	Raw readers.
`readValidatedBody(fn)`, `readValidatedBodyJson(fn)`, `readValidatedBodyText(fn)`, `readValidatedBodyFormData(fn)`	Read the body, then run your validator. Its return value is the result.
`asWeb()`	A web-standard `Request` view of the same message.

Readers return unknown. Narrow the result with your own validator. Any function works, so Zod, Valibot, or a hand-written guard are all valid:

// src/routes/users.post.ts
import { HttpCodes, Route } from '@wolfstar/plugin-api';
import { z } from 'zod';

const User = z.object({ name: z.string() });

export class CreateUserRoute extends Route {
	public async run(request: Route.Request, response: Route.Response) {
		const user = await request.readValidatedBodyJson((data) => User.parse(data));
		response.status(HttpCodes.Created).json(user);
	}
}

A malformed body rejects. An uncaught rejection becomes a generic 500. The plugin logs the parser message and never sends it to the client.

Writing the response

ApiResponse (Route.Response) extends ServerResponse. Every helper returns void except status and setContentType, which return this so they chain:

response.status(HttpCodes.Created).json({ id });
response.ok(); // 200, body "OK"
response.noContent(); // 204
response.badRequest({ error: 'Missing name' });
response.text('hello');
response.html(200, '<h1>hi</h1>');
response.error(500); // generic JSON error for a status code

Available helpers: ok, created, noContent, badRequest, unauthorized, forbidden, notFound, methodNotAllowed, conflict, error, respond, status, json, text, image, html, and setContentType. HttpCodes is re-exported from @wolfstar/http-framework, so you can import it from either package.

Cookies

The built-in cookies middleware creates response.cookies, a CookieStore. It is a Map of the parsed Cookie header. Cookies you add or remove are written to Set-Cookie when the response is sent. They are marked Secure when NODE_ENV=production.

const session = response.cookies.get('session');
response.cookies.add('session', 'abc', { domain: 'example.com', maxAge: 3600 });
response.cookies.remove('old');

The CookieStore skips malformed Cookie pairs (bad percent-encoding or a missing =). When the request Host is an IP address there is no default cookie domain, so pass domain explicitly.

Writing a middleware

Middlewares are Middleware pieces loaded from a middlewares directory. They run in ascending position order (default 1000) before route dispatch. A middleware stops the chain by ending the response:

// src/middlewares/requestId.ts
import { Middleware } from '@wolfstar/plugin-api';
import { randomUUID } from 'node:crypto';

export class RequestIdMiddleware extends Middleware {
	public constructor(context: Middleware.LoaderContext) {
		super(context, { position: 15 });
	}

	public run(request: Middleware.Request, response: Middleware.Response) {
		response.setHeader('X-Request-Id', randomUUID());
	}
}

Built-in middlewares:

Name	Position	Behavior
`headers`	10	Sets `Date` and the CORS headers. Ends the response early with an empty `200` for `OPTIONS` (unless the route handles `OPTIONS`), `404`, or `405`.
`body`	20	Answers `413` when the declared `Content-Length` exceeds the route’s `maximumBodyLength`.
`cookies`	30	Creates `response.cookies`.

`ServerOptions`

Pass these under the api key of your ClientOptions:

Option	Default	Description
`prefix`	`undefined`	Path segment prefix applied to every route.
`origin`	`'*'`	`Access-Control-Allow-Origin` header value.
`maximumBodyLength`	`1024 * 1024 * 50`	Default maximum `Content-Length`, in bytes. A route can override it.
`server`	`undefined`	Raw options forwarded to `node:http`’s `createServer`.
`listenOptions`	`{ port: 4000 }`	Raw options forwarded to `server.listen()`.
`automaticallyConnect`	`true`	Whether to start listening during the `postListen` hook.

Server#connect() rejects (for example with EADDRINUSE) instead of throwing uncaught.

Events

container.server emits ServerEvent members. The built-in listeners implement the pipeline request → middlewares → routerFound / routerBranchNotFound / routerBranchMethodNotAllowed. routerFound then emits middlewareSuccess (the route runs) or middlewareFailure (a middleware already ended the response). Errors surface as middlewareError or routeError. Both built-in listeners log with container.logger.fatal(error) and answer a generic 500. ServerEvent.Error carries an optional request and response. Listener piece names are PascalCase (for example PluginServerRequest).

Migrating from 2.x

Version 3.0.0 drops Node.js 20. The only breaking change is the Node.js requirement, which is now >=22.0.0. The API is the same as in 2.x, so upgrade Node.js and bump the package:

pnpm add @wolfstar/plugin-api@^3.0.0

Migrating from 1.x

Version 2.0.0 contains breaking changes. Update your code as follows:

1.x	2.x
`ApiServer`	`Server`
`ApiServerOptions`	`ServerOptions`
`ApiServerEvents`	`ServerEvents`
`ApiServerEvent`	`ServerEvent`
`ApiPlugin`	`Api`
`HttpMethod`	`MethodName`
`response.json(data, code)`	`response.status(code).json(data)`
`request.readBodyJson<T>(limit)`	`request.readBodyJson()` (returns `unknown`) or `readValidatedBodyJson(fn)`
`request.query.get('key')`	`request.query.key`

Behavior changes:

No implicit GET. A route without methods matches nothing, and its path answers 404. Add a method suffix to the file name or pass methods (see Writing a route).
Response helpers return void. Only status and setContentType chain.
Body limit. readBodyJson() no longer takes a limit argument. Set maximumBodyLength in ServerOptions or per route instead.
request.query is a plain Record<string, string | string[]>, no longer a URLSearchParams.
OPTIONS pre-flight requests answer 200 with an empty body instead of 204. 404 and 405 responses from the headers middleware also have empty bodies.
Listener piece names are PascalCase, and ServerEvent.Error carries an optional request and response.
Requirements. @wolfstar/http-framework ^3.6.0 || ^5.0.0 || ^6.0.0. Version 3.0.0 also requires Node.js >=22.0.0 (see Migrating from 2.x).

Scope

The plugin matches @sapphire/plugin-api 8.3.1 except for authentication.

Authentication and OAuth2 are not ported. Auth, ServerOptions.auth, ApiRequest.auth, the auth middleware, and the built-in OAuth routes (loadRoutes) do not exist in this plugin. Write your own auth middleware and routes as needed.

Also not ported: the Client.server augmentation (that is the interactions server here) and the CommonJS build. The framework’s postListen hook replaces preLogin.

Known limitations

These behaviors are kept as they are upstream:

Chunked request bodies without a Content-Length are not length-limited by the body middleware.
A request with a Content-Length but no Content-Type bypasses the body limit.
The IPv6 Host header edge case is not fixed.
response.cookies.add() without an explicit domain throws when the request Host is an IP address. The error surfaces as a route error and a generic 500.

Fixed relative to upstream

RouterBranch#path no longer drops ancestor segments.
Removing a route no longer deletes sibling methods or indexes the wrong branch.
supportedMethods includes grandchildren.
CookieStore no longer crashes on malformed Cookie headers.
A :8080 Host header no longer produces a NaN port.
Server#connect() rejects instead of throwing uncaught when the port is in use.
The request stream is closed when a client disconnects mid-body.

Infrastructure

Shared pieces

Platform helpers

Plugins

npm

Source

Description

Installation

Usage

Activating with `modules`

Writing a route

Reading the request

Writing the response

Cookies

Writing a middleware

`ServerOptions`

Events

Migrating from 2.x

Migrating from 1.x

Scope

Known limitations

Fixed relative to upstream

npm

Source

​Description

​Installation

​Usage

​Activating with modules

​Writing a route

​Reading the request

​Writing the response

​Cookies

​Writing a middleware

​ServerOptions

​Events

​Migrating from 2.x

​Migrating from 1.x

​Scope

​Known limitations

​Fixed relative to upstream

Description

Installation

Usage

Activating with `modules`

Writing a route

Reading the request

Writing the response

Cookies

Writing a middleware

`ServerOptions`

Events

Migrating from 2.x

Migrating from 1.x

Scope

Known limitations

Fixed relative to upstream