@wolfstar/plugin-api 0.0.0-next-20260816113531

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,114 @@
+# @wolfstar/plugin-api
+
+A plugin for [`@wolfstar/http-framework`](https://www.npmjs.com/package/@wolfstar/http-framework),
+ported from [`@sapphire/plugin-api`](https://github.com/sapphiredev/plugins/tree/main/packages/api).
+It exposes a **standalone** REST API server — for health checks, dashboards, or webhooks from other
+services — built on the same `@sapphire/pieces` `Route`/`Middleware` conventions.
+
+It is intentionally independent from `Client#server` (the interactions webhook): that server already
+claims every path on its port and 404s anything that doesn't match, so this plugin binds its own
+`ApiServer` on a separate port instead of trying to share the same listener.
+
+## Installation
+
+```bash
+pnpm add @wolfstar/plugin-api
+```
+
+## Usage
+
+Import the side-effecting `register` entrypoint **before** you create your `Client`:
+
+```ts
+import "@wolfstar/plugin-api/register";
+import { Client } from "@wolfstar/http-framework";
+
+const client = new Client({
+  api: {
+    listenOptions: { port: 4000 },
+    origin: "*",
+  },
+});
+
+await client.load();
+await client.listen({ port: 8080 }); // interactions webhook; the API server starts right after
+```
+
+## Writing a route
+
+Routes are `Route` pieces loaded from a `routes` directory, exactly like `commands`/`listeners`:
+
+```ts
+// src/routes/health.get.ts
+import { HttpCodes } from "@wolfstar/http-framework";
+import { Route } from "@wolfstar/plugin-api";
+
+export class HealthRoute extends Route {
+  public run(_request: Route.Request, response: Route.Response) {
+    response.json({ status: "ok" }, HttpCodes.OK);
+  }
+}
+```
+
+The route's path and method are inferred from its location: `src/routes/health.get.ts` registers
+`GET /health`. A folder named `[id]` becomes a dynamic segment (`request.params.id`), and a
+`(group)`-style folder is skipped when building the path. Both can be overridden explicitly:
+
+```ts
+export class HealthRoute extends Route {
+  public constructor(context: Route.LoaderContext) {
+    super(context, { route: "/status", methods: ["GET", "HEAD"] });
+  }
+
+  public run(request: Route.Request, response: Route.Response) {
+    response.json({ status: "ok", method: request.method });
+  }
+}
+```
+
+## Writing a middleware
+
+Middlewares are `Middleware` pieces loaded from a `middlewares` directory, run in ascending
+`position` order before route dispatch; a middleware stops the chain by ending the response:
+
+```ts
+// 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: `headers` (position 10, sets CORS headers and short-circuits `OPTIONS`
+pre-flight requests) and `body` (position 20, rejects requests whose `Content-Length` exceeds
+`maximumBodyLength`).
+
+## `ApiServerOptions`
+
+| Option                 | Default            | Description                                              |
+| ---------------------- | ------------------ | -------------------------------------------------------- |
+| `prefix`               | `undefined`        | Path segment prefix applied to every route.              |
+| `origin`               | `'*'`              | `Access-Control-Allow-Origin` header value.              |
+| `maximumBodyLength`    | `1024 * 1024 * 50` | Maximum accepted `Content-Length`, in bytes.             |
+| `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. |
+
+## Scope
+
+Ported faithfully: the `Route`/`RouteStore` piece conventions, the filesystem-routing/dynamic-segment
+trie router (`RouterRoot`/`RouterBranch`/`RouterNode`), the position-ordered `Middleware`/`MiddlewareStore`
+chain, and the listener-driven request dispatch pipeline (`request` → middlewares → `routerFound` /
+`routerBranchNotFound` / `routerBranchMethodNotAllowed` → route `run`).
+
+**Not ported** (out of scope for this webhook-only framework, kept for a future release): cookies,
+OAuth2/session auth, and the built-in `oauth/callback`, `oauth/logout` routes from the original
+`@sapphire/plugin-api`. Add your own auth middleware/routes as needed.

package/dist/esm/index-D-l34LxR.d.ts

@@ -0,0 +1,314 @@
+import { IncomingMessage, Server, ServerOptions, ServerResponse } from "node:http";
+import { AsyncEventEmitter } from "@vladfrangu/async_event_emitter";
+import { Piece, PieceOptions, Store } from "@sapphire/pieces";
+import { ListenOptions } from "node:net";
+//#region src/lib/http/ApiResponse.d.ts
+declare class ApiResponse extends ServerResponse<ApiRequest> {
+  status(statusCode: number): this;
+  json(body: unknown, statusCode?: number): this;
+  text(body: string, statusCode?: number): this;
+  noContent(): this;
+  notFound(body?: unknown): this;
+  methodNotAllowed(body?: unknown): this;
+  badRequest(body?: unknown): this;
+  error(statusCode?: number, body?: unknown): this;
+}
+//#endregion
+//#region src/lib/http/HttpMethod.d.ts
+/**
+ * The HTTP methods that a {@link Route} can be registered for.
+ */
+declare const HttpMethods: readonly ["DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT"];
+type HttpMethod = (typeof HttpMethods)[number];
+//#endregion
+//#region src/lib/structures/Route.d.ts
+type Awaitable<T> = T | PromiseLike<T>;
+/**
+ * A single HTTP endpoint. The route's path and methods are either given explicitly via
+ * {@link Route.Options.route}/{@link Route.Options.methods}, or inferred from the piece's file
+ * system location: directories become path segments (`(group)`-style directories are skipped,
+ * `index` collapses into its parent), `[param]` segments become dynamic, and a `.<method>`
+ * filename suffix (e.g. `hello.post.ts`) implies that HTTP method.
+ */
+declare abstract class Route<Options extends Route.Options = Route.Options> extends Piece<Options, "routes"> {
+  /**
+   * The normalized path segments this route is registered under, e.g. `['users', '[id]']`.
+   */
+  readonly path: readonly string[];
+  /**
+   * The HTTP methods this route responds to.
+   */
+  readonly methods: ReadonlySet<HttpMethod>;
+  constructor(context: Route.LoaderContext, options: Options);
+  /**
+   * Handles every method this route was registered for. Branch on `request.method` when a route
+   * needs to support multiple methods.
+   */
+  abstract run(request: ApiRequest, response: ApiResponse): Awaitable<unknown>;
+}
+declare namespace Route {
+  type LoaderContext = Piece.LoaderContext<"routes">;
+  interface Options extends PieceOptions {
+    /**
+     * An explicit route path, e.g. `/users/[id]`. If omitted, the path is inferred from the
+     * piece's directory structure and file name.
+     */
+    route?: `/${string}`;
+    /**
+     * The HTTP methods this route responds to. If omitted, inferred from a `.<method>` filename
+     * suffix (e.g. `hello.post.ts`), defaulting to `GET`.
+     */
+    methods?: readonly HttpMethod[];
+  }
+}
+//#endregion
+//#region src/lib/structures/router/RouterNode.d.ts
+/**
+ * A single path segment's registered routes, keyed by HTTP method.
+ */
+declare class RouterNode extends Map<HttpMethod, Route> {
+  readonly branch: RouterBranch;
+  constructor(branch: RouterBranch);
+  /**
+   * Walks up the branch chain collecting the values captured by dynamic (`[param]`) segments.
+   * @param parts The path segments of the matched request, in the same order used to reach this node.
+   */
+  extractParameters(parts: readonly string[]): Record<string, string>;
+}
+//#endregion
+//#region src/lib/structures/router/RouterBranch.d.ts
+/**
+ * A single segment of the route trie. Each branch owns exactly one {@link RouterNode} (its
+ * method-to-route map) and may have any number of static children plus at most one dynamic
+ * (`[param]`) child, which is only checked after every static child fails to match.
+ */
+declare class RouterBranch {
+  readonly name: string;
+  readonly dynamic: boolean;
+  readonly parent: RouterBranch | null;
+  readonly node: RouterNode;
+  private readonly staticChildren;
+  private dynamicChild;
+  constructor(name: string, dynamic: boolean, parent: RouterBranch | null);
+  matches(part: string): boolean;
+  protected insertAt(parts: readonly string[], index: number, route: Route): RouterNode;
+  protected removeAt(parts: readonly string[], index: number, route: Route): boolean;
+  protected findAt(parts: readonly string[], index: number): RouterBranch | null;
+}
+//#endregion
+//#region src/lib/http/ApiRequest.d.ts
+declare class ApiRequest extends IncomingMessage {
+  /**
+   * The parsed query string parameters.
+   */
+  query: URLSearchParams;
+  /**
+   * The extracted dynamic (`[param]`) path segment values.
+   */
+  params: Record<string, string>;
+  /**
+   * The matched router branch for this request's pathname, if any.
+   */
+  routerNode: RouterBranch | null;
+  /**
+   * The matched route for this request's pathname and method, if any.
+   */
+  route: Route | null;
+  /**
+   * Reads the full request body as a UTF-8 string.
+   * @param limit The maximum number of bytes to read before rejecting. Defaults to 1 MiB.
+   */
+  readBodyText(limit?: number): Promise<string>;
+  /**
+   * Reads and parses the request body as JSON.
+   * @param limit The maximum number of bytes to read before rejecting. Defaults to 1 MiB.
+   */
+  readBodyJson<T = unknown>(limit?: number): Promise<T>;
+}
+//#endregion
+//#region src/lib/structures/Middleware.d.ts
+/**
+ * A piece that runs on every incoming request, in ascending {@link Middleware.position} order,
+ * before route dispatch. A middleware stops the chain implicitly by ending the response
+ * (`response.writableEnded`); there is no explicit `next()` callback.
+ */
+declare abstract class Middleware<Options extends Middleware.Options = Middleware.Options> extends Piece<Options, "middlewares"> {
+  /**
+   * The built-in middlewares use the following positions:
+   * - `headers`: 10 (CORS headers, 404/405 short-circuit)
+   * - `body`: 20 (`Content-Length` validation)
+   */
+  readonly position: number;
+  constructor(context: Middleware.LoaderContext, options: Options);
+  abstract run(request: ApiRequest, response: ApiResponse): Awaitable<unknown>;
+}
+declare namespace Middleware {
+  type LoaderContext = Piece.LoaderContext<"middlewares">;
+  interface Options extends PieceOptions {
+    /**
+     * Middlewares run in ascending order of this value.
+     * @default 1000
+     */
+    position?: number;
+  }
+}
+//#endregion
+//#region src/lib/structures/MiddlewareStore.d.ts
+declare class MiddlewareStore extends Store<Middleware, "middlewares"> {
+  /**
+   * Enabled middlewares, kept sorted in ascending {@link Middleware.position} order.
+   */
+  readonly sortedMiddlewares: Middleware[];
+  constructor();
+  /**
+   * Runs every enabled middleware in order, stopping early once the response has ended.
+   */
+  run(request: ApiRequest, response: ApiResponse): Promise<void>;
+  set(key: string, value: Middleware): this;
+  delete(key: string): boolean;
+  clear(): void;
+}
+//#endregion
+//#region src/lib/structures/router/RouterRoot.d.ts
+/**
+ * The root of the route trie, owned by {@link RouteStore.router}. Provides the public
+ * add/remove/find API plus the static path-parsing helpers used by {@link Route}'s constructor.
+ */
+declare class RouterRoot extends RouterBranch {
+  constructor();
+  add(route: Route): RouterNode;
+  remove(route: Route): boolean;
+  find(parts: readonly string[]): RouterBranch | null;
+  /**
+   * Splits a `/`-delimited path into its non-empty segments.
+   */
+  static normalize(path?: string | null): string[];
+  /**
+   * Builds a route path from a piece's directory structure and file name: `(group)`-style
+   * directories are skipped, and a file named `index` collapses into its parent directory.
+   */
+  static makeRoutePathForPiece(directories: readonly string[], name: string): string;
+  /**
+   * Extracts a trailing `.<method>` suffix from a piece name, e.g. `hello.post` → `POST`.
+   */
+  static extractMethod(name: string): HttpMethod | null;
+}
+//#endregion
+//#region src/lib/structures/RouteStore.d.ts
+declare class RouteStore extends Store<Route, "routes"> {
+  /**
+   * The trie used to match an incoming request's pathname to a registered {@link Route}.
+   */
+  readonly router: RouterRoot;
+  constructor();
+}
+//#endregion
+//#region src/lib/http/ApiServer.d.ts
+declare enum ApiServerEvent {
+  Error = "error",
+  Request = "request",
+  RouterBranchNotFound = "routerBranchNotFound",
+  RouterBranchMethodNotAllowed = "routerBranchMethodNotAllowed",
+  RouterFound = "routerFound",
+  RouteError = "routeError",
+  MiddlewareError = "middlewareError"
+}
+interface ApiServerEvents {
+  [ApiServerEvent.Error]: [error: Error];
+  [ApiServerEvent.Request]: [request: ApiRequest, response: ApiResponse];
+  [ApiServerEvent.RouterBranchNotFound]: [request: ApiRequest, response: ApiResponse];
+  [ApiServerEvent.RouterBranchMethodNotAllowed]: [request: ApiRequest, response: ApiResponse];
+  [ApiServerEvent.RouterFound]: [request: ApiRequest, response: ApiResponse];
+  [ApiServerEvent.RouteError]: [error: unknown, request: ApiRequest, response: ApiResponse];
+  [ApiServerEvent.MiddlewareError]: [error: unknown, request: ApiRequest, response: ApiResponse];
+}
+interface ApiServerOptions {
+  /**
+   * A path segment prefix applied to every route, e.g. `/api`.
+   */
+  prefix?: string;
+  /**
+   * The value of the `Access-Control-Allow-Origin` header set by the built-in `headers` middleware.
+   * @default '*'
+   */
+  origin?: string;
+  /**
+   * The maximum request body size in bytes, enforced by the built-in `body` middleware.
+   * @default 1024 * 1024 * 50
+   */
+  maximumBodyLength?: number;
+  /**
+   * Raw options forwarded to `node:http`'s `createServer`.
+   */
+  server?: ServerOptions;
+  /**
+   * Raw options forwarded to `Server#listen`.
+   * @default { port: 4000 }
+   */
+  listenOptions?: ListenOptions;
+  /**
+   * Whether to start listening automatically once the interaction webhook is up (during the
+   * `postListen` plugin hook).
+   * @default true
+   */
+  automaticallyConnect?: boolean;
+}
+/**
+ * A standalone HTTP server for auxiliary REST routes (health checks, dashboards, webhooks from
+ * other services, etc). It is deliberately independent from {@link Client.server}, which is
+ * reserved for the Discord interactions webhook.
+ */
+declare class ApiServer extends AsyncEventEmitter<ApiServerEvents> {
+  readonly routes: RouteStore;
+  readonly middlewares: MiddlewareStore;
+  readonly server: Server<typeof ApiRequest, typeof ApiResponse>;
+  readonly options: ApiServerOptions;
+  constructor(options?: ApiServerOptions);
+  /**
+   * Starts listening for requests.
+   */
+  connect(): Promise<void>;
+  /**
+   * Stops the server from accepting new connections.
+   */
+  disconnect(): Promise<void>;
+}
+//#endregion
+//#region src/listeners/_load.d.ts
+/**
+ * Registers the built-in dispatch-pipeline listeners into the framework's existing listener
+ * store, targeting the `server` container entry (see {@link ApiServer}).
+ */
+declare function loadListeners(): Promise<void>;
+//#endregion
+//#region src/middlewares/_load.d.ts
+/**
+ * Registers the built-in middlewares (`headers`, `body`) into {@link ApiServer.middlewares}.
+ */
+declare function loadMiddlewares(): Promise<void>;
+//#endregion
+//#region src/index.d.ts
+declare module "@wolfstar/http-framework" {
+  interface ClientOptions {
+    /**
+     * Options for the auxiliary REST API server registered by `@wolfstar/plugin-api`.
+     */
+    api?: ApiServerOptions;
+  }
+}
+declare module "@sapphire/pieces" {
+  interface StoreRegistryEntries {
+    routes: RouteStore;
+    middlewares: MiddlewareStore;
+  }
+  interface Container {
+    /**
+     * The auxiliary REST API server registered by `@wolfstar/plugin-api`. Independent from the
+     * Discord interactions webhook server (`Client#server`).
+     */
+    server: ApiServer;
+  }
+}
+//#endregion
+export { HttpMethods as _, ApiServerEvents as a, RouterRoot as c, ApiRequest as d, RouterBranch as f, HttpMethod as g, Route as h, ApiServerEvent as i, MiddlewareStore as l, Awaitable as m, loadListeners as n, ApiServerOptions as o, RouterNode as p, ApiServer as r, RouteStore as s, loadMiddlewares as t, Middleware as u, ApiResponse as v };
+//# sourceMappingURL=index-D-l34LxR.d.ts.map

package/dist/esm/index-D-l34LxR.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-D-l34LxR.d.ts","names":[],"sources":["../../src/lib/http/ApiResponse.ts","../../src/lib/http/HttpMethod.ts","../../src/lib/structures/Route.ts","../../src/lib/structures/router/RouterNode.ts","../../src/lib/structures/router/RouterBranch.ts","../../src/lib/http/ApiRequest.ts","../../src/lib/structures/Middleware.ts","../../src/lib/structures/MiddlewareStore.ts","../../src/lib/structures/router/RouterRoot.ts","../../src/lib/structures/RouteStore.ts","../../src/lib/http/ApiServer.ts","../../src/listeners/_load.ts","../../src/middlewares/_load.ts","../../src/index.ts"],"mappings":";;;;;cAIa,oBAAoB,eAAe;EACvC,OAAO;EAKP,KAAK,eAAe;EAQpB,KAAK,cAAc;EAQnB;EAMA,SAAS;EAIT,iBAAiB;EAIjB,WAAW;EAIX,MACL,qBACA;;;;;;;cC3CS;KAED,qBAAqB;;;KCCrB,UAAU,KAAK,IAAI,YAAY;;;;;;;;uBASrB,MAAM,gBAAgB,MAAM,UAAU,MAAM,iBAAiB,MACjF;;;;WAMgB;;;;WAKA,SAAS,YAAY;EAElB,YAAA,SAAS,MAAM,eAAe,SAAS;;;;;WA6B1C,IAAI,SAAS,YAAY,UAAU,cAAc;;kBAGlD;OACH,gBAAgB,MAAM;YAEjB,gBAAgB;;;;;IAK/B;;;;;IAMA,mBAAmB;;;;;;;;cCpEV,mBAAmB,IAAI,YAAY;WAC9B,QAAQ;EAEL,YAAA,QAAQ;;;;;EASpB,kBAAkB,2BAA2B;;;;;;;;;cCXzC;WACK;WACA;WACA,QAAQ;WACR,MAAM;mBAEL;UACT;EAEW,YAAA,cAAc,kBAAkB,QAAQ;EAOpD,QAAQ;YAIL,SAAS,0BAA0B,eAAe,OAAO,QAAQ;YAyBjE,SAAS,0BAA0B,eAAe,OAAO;YAczD,OAAO,0BAA0B,gBAAgB;;;;cC/DhD,mBAAmB;;;;EAIvB,OAAO;;;;EAKP,QAAQ;;;;EAKR,YAAY;;;;EAKZ,OAAO;;;;;EAMD,aAAa,iBAAsB;;;;;EAiBnC,aAAa,aAAa,iBAAiB,QAAQ;;;;;;;;;uBCpC5C,WACpB,gBAAgB,WAAW,UAAU,WAAW,iBACxC,MAAM;;;;;;WAME;EAEG,YAAA,SAAS,WAAW,eAAe,SAAS;WAK/C,IAAI,SAAS,YAAY,UAAU,cAAc;;kBAGlD;OACH,gBAAgB,MAAM;YAEjB,gBAAgB;;;;;IAK/B;;;;;cC/BS,wBAAwB,MAAM;;;;WAIzB,mBAAmB;;;;;EAStB,IAAI,SAAS,YAAY,UAAU,cAAc;EAO9C,IAAI,aAAa,OAAO;EAUxB,OAAO;EAOP;;;;;;;;cC/BL,mBAAmB;;EAKvB,IAAI,OAAO,QAAQ;EAInB,OAAO,OAAO;EAId,KAAK,2BAA2B;;;;SAOzB,UAAU;;;;;SASV,sBAAsB,gCAAgC;;;;SAmBtD,cAAc,eAAe;;;;cCtDhC,mBAAmB,MAAM;;;;WAIpB,QAAM;;;;;aCIZ;EACV;EACA;EACA;EACA;EACA;EACA;EACA;;UAGe;GACd,eAAe,SAAS,OAAO;GAC/B,eAAe,WAAW,SAAS,YAAY,UAAU;GACzD,eAAe,wBAAwB,SAAS,YAAY,UAAU;GACtE,eAAe,gCAAgC,SAAS,YAAY,UAAU;GAC9E,eAAe,eAAe,SAAS,YAAY,UAAU;GAC7D,eAAe,cAAc,gBAAgB,SAAS,YAAY,UAAU;GAC5E,eAAe,mBAAmB,gBAAgB,SAAS,YAAY,UAAU;;UAGnE;;;;EAIf;;;;;EAMA;;;;;EAMA;;;;EAKA,SAAS;;;;;EAMT,gBAAgB;;;;;;EAOhB;;;;;;;cAQW,kBAAkB,kBAAkB;WAC/B,QAAQ;WACR,aAAa;WACb,QAAQ,cAAsB,mBAAmB;WACjD,SAAS;EAEN,YAAA,UAAS;;;;EA0BrB,WAAW;;;;EAoBX,cAAc;;;;;;;;iBCnHD,iBAAiB;;;;;;iBCLjB,mBAAmB;;;;YCa7B;;;;IAIR,MAAM;;;;YAKE;IACR,QAAQ;IACR,aAAa;;YAGL;;;;;IAKR,QAAQ"}

package/dist/esm/index.d.ts

@@ -0,0 +1,2 @@
+import { _ as HttpMethods, a as ApiServerEvents, c as RouterRoot, d as ApiRequest, f as RouterBranch, g as HttpMethod, h as Route, i as ApiServerEvent, l as MiddlewareStore, m as Awaitable, n as loadListeners, o as ApiServerOptions, p as RouterNode, r as ApiServer, s as RouteStore, t as loadMiddlewares, u as Middleware, v as ApiResponse } from "./index-D-l34LxR.js";
+export { ApiRequest, ApiResponse, ApiServer, ApiServerEvent, ApiServerEvents, ApiServerOptions, Awaitable, HttpMethod, HttpMethods, Middleware, MiddlewareStore, Route, RouteStore, RouterBranch, RouterNode, RouterRoot, loadListeners, loadMiddlewares };

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+import { a as RouteStore, c as RouterBranch, d as MiddlewareStore, f as Middleware, i as ApiServerEvent, l as RouterNode, m as ApiRequest, n as loadListeners, o as Route, p as ApiResponse, r as ApiServer, s as RouterRoot, t as loadMiddlewares, u as HttpMethods } from "./src-CscMIChC.js";
+
+export { ApiRequest, ApiResponse, ApiServer, ApiServerEvent, HttpMethods, Middleware, MiddlewareStore, Route, RouteStore, RouterBranch, RouterNode, RouterRoot, loadListeners, loadMiddlewares };

package/dist/esm/register.d.ts

@@ -0,0 +1,20 @@
+import "./index-D-l34LxR.js";
+import { Client, ClientOptions, Plugin, postInitialization, postListen } from "@wolfstar/http-framework";
+//#region src/register.d.ts
+/**
+ * Registers a standalone {@link ApiServer} for auxiliary REST routes (health checks, dashboards,
+ * webhooks from other services, etc), independent from the Discord interactions webhook server.
+ *
+ * Activate by importing the side-effecting entrypoint before creating the client:
+ *
+ * ```ts
+ * import '@wolfstar/plugin-api/register';
+ * ```
+ */
+declare class ApiPlugin extends Plugin {
+  static [postInitialization](this: Client, options: ClientOptions): void;
+  static [postListen](this: Client, options: ClientOptions): Promise<void>;
+}
+//#endregion
+export { ApiPlugin };
+//# sourceMappingURL=register.d.ts.map

package/dist/esm/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","names":[],"sources":["../../src/register.ts"],"mappings":";;;;;;;;;;;;;cAuBa,kBAAkB;UACd,oBAAoB,MAAM,QAAQ,SAAS;UAerC,YAAY,MAAM,QAAQ,SAAS,gBAAgB"}