skills/plugins/document-navigator/docs/api-stack/api/api

@suaveplan/api - Thin Hono-based orchestrator for the Suaveplan API stack — composes pre-built PluginRegistry, OpenAPIRegistry, MiddlewareChain, TenantResolver, and MigrationRunner into a SuaveApp runtime. Monotonic AppState FSM, configurable health routes, optional single-AsyncLocalStorage RequestContext, Zod-validated multi-source config loader (file → env-file → env-vars), name-addressable middleware chain with insert-target enforcement, full-status-passthrough error handler, conditional CORS rate-limit headers, fluent AppBuilder with real tenant() wiring. Server-tier (Node + Bun).

The thin Hono-based application orchestrator for the Suaveplan API stack. Composes the four sibling packages — @suaveplan/api-plugin, @suaveplan/api-tenant, @suaveplan/api-openapi, and @suaveplan/api-migrations — into a runnable HTTP service with a monotonic state FSM, a name-addressable middleware chain, a Zod- validated multi-source config loader, configurable health routes, an optional single-AsyncLocalStorage RequestContext, and a typed lifecycle event bus.

Documentation tree

• app — The app module owns the SuaveApp class — the Hono-based orchestrator that composes the four sibling packages into a…
  • app — The app module owns the SuaveApp class — the Hono-based orchestrator that composes the four sibling packages into a…
  • health-routes — The health-routes module wires the configurable health-probe routes (/health, /ready, optional /live) onto a `O…
  • migrations — The migrations module is the tiny helper that connects the @suaveplan/api-migrations MigrationRunner to the `Suav…
  • request-context — The request-context module owns the single AsyncLocalStorage instance that the SuaveApp orchestrator uses to prop…
  • timeout — The timeout module ships a single internal-facing helper used by SuaveApp.stop to enforce the shutdown budget. It r…
• builder — The builder module ships the fluent AppBuilder class, the defineApp() factory, and the quickstart() one-call he…
  • assemble — The assemble module owns the pure helpers that the fluent AppBuilder delegates to during .build(): configuration…
  • builder — The builder module ships the fluent AppBuilder class, the defineApp() factory, and the quickstart() one-call he…
  • cors-bridge — The cors-bridge module owns the two helpers AppBuilder uses to translate between CorsOptions (the runtime middlew…
• config — The config module defines every Zod schema that the @suaveplan/api orchestrator validates against. It is the single…
  • config — The config module defines every Zod schema that the @suaveplan/api orchestrator validates against. It is the single…
  • loader — The loader module assembles an AppConfigInput from four sources — schema defaults, a base config file, an environme…
  • validator — The validator module wraps AppConfigSchema.safeParse with the package's typed error path. Every validation failure…
• error-codes — The error-codes module owns the stable string registry of API.* failure codes raised by the @suaveplan/api orches…
  • error-codes — The error-codes module owns the stable string registry of API.* failure codes raised by the @suaveplan/api orches…
• event-integration — The event-integration module exposes the typed lifecycle event surface that the SuaveApp orchestrator publishes to.…
  • event-bridge — The event-integration module exposes the typed lifecycle event surface that the SuaveApp orchestrator publishes to.…
• chain — The chain module owns the order-aware, name-addressable list of Hono middlewares that the SuaveApp orchestrator han…
• composition — The composition module ships four pure higher-order functions that compose Hono middlewares into one another. They ar…
• cors — The cors module wraps hono/cors with the orchestrator's CORS configuration shape, registers the resulting handler u…
• error-handler — The error-handler module ships the catch-all middleware that converts every throwable raised by downstream handlers i…
• logger — The logger module ships a Hono middleware that emits one structured log line per request, plus three drop-in formatte…
• request-id — The request-id module assigns every inbound request a stable identifier that survives across middleware, route handle…
• services — The registry-augmentation module declares the canonical host services that @suaveplan/api seeds into the `PluginReg…
  • registry-augmentation — The registry-augmentation module declares the canonical host services that @suaveplan/api seeds into the `PluginReg…
• types — The types module is the public type contract for the @suaveplan/api orchestrator. Every other module in the package…
  • api — The types module is the public type contract for the @suaveplan/api orchestrator. Every other module in the package…

Install

bun add @suaveplan/api

Quick start

import { defineApp } from "@suaveplan/api";
import { definePlugin } from "@suaveplan/api-plugin";

const billing = definePlugin({ name: "billing", version: "1.0.0" });

const app = await defineApp()
    .name("billing-api")
    .version("1.0.0")
    .port(8080)
    .skipConfigFile()
    .openapi({ title: "Billing", version: "1.0.0" })
    .use(billing)
    .start();

AppBuilder fluent example

import { defineApp } from "@suaveplan/api";
import { headerResolver } from "@suaveplan/api-tenant";
import { createMigrationRunner, createSqliteAdapter } from "@suaveplan/api-migrations";

const runner = createMigrationRunner(createSqliteAdapter(sqliteClient));

const app = await defineApp()
    .name("orders")
    .version("2.0.0")
    .env("production")
    .cors({ origins: ["https://app.example.com"], withRateLimitHeaders: true })
    .openapi({ title: "Orders", version: "2.0.0" })
    .useAsyncLocalStorage()
    .tenant(headerResolver({ headerName: "x-tenant-id", lookupFn }))
    .migrations({ runner, dirPath: "./migrations" })
    .use(plugin)
    .start();

Config file format

suaveplan.config.{ts,js,json} files are read from the working directory (override via .configFile({ configDir })). Layered with environment-specific overrides (suaveplan.config.production.json) and environment variables (SUAVEPLAN_SERVER_PORT=4000).

YAML and TOML are NOT supported (the upstream package advertised them but threw at runtime — drops the union entries).

ALS opt-in

import { getCurrentRequestContext } from "@suaveplan/api";

const app = await defineApp()
    .name("trace")
    .openapi({ title: "Trace", version: "0.1.0" })
    .skipConfigFile()
    .useAsyncLocalStorage()
    .start();

// Deep in a request handler:
const ctx = getCurrentRequestContext();
// ctx.requestId, ctx.tenant?, ctx.user?, ctx.app

Modules

• ./src/error-codes/error-codes.md — API_CODES + ApiError.
• ./src/types/api.md — public type contract.
• ./src/config/config.md — Zod schemas.
• ./src/config/loader.md — multi-source loader.
• ./src/config/validator.md — typed validation.
• ./src/middleware/chain.md — name-addressable chain.
• ./src/middleware/cors.md — createCors (conditional rate-limit headers).
• ./src/middleware/error-handler.md — global error handler (full status passthrough).
• ./src/middleware/logger.md — request logger + 3 formatters.
• ./src/middleware/request-id.md — request id + 3 generators.
• ./src/middleware/composition.md — combineMiddleware & friends.
• ./src/event-integration/event-bridge.md — typed lifecycle bus.
• ./src/app/app.md — SuaveApp orchestrator.
• ./src/app/health-routes.md — configurable health routes.
• ./src/app/request-context.md — single ALS.
• ./src/app/migrations.md — migration-runner integration helper.
• ./src/app/timeout.md — runWithTimeout helper.
• ./src/builder/builder.md — fluent AppBuilder.
• ./src/builder/assemble.md — pure assembly helpers.
• ./src/builder/cors-bridge.md — config ↔ middleware bridge.

Migration-runner integration

When MigrationsOptions is supplied and config.migrations.runBeforePluginInit is true (the default), the runner executes before PluginRegistry.initialize() so plugin onInit hooks see a migrated database. Pass an explicit files array for deterministic in-memory tests, or dirPath to scan a real directory.

Error codes

Code	When raised
API.INVALID_CONFIG	validateConfig / validatePluginConfig
API.INVALID_STATE	SuaveApp.initialize/start from wrong state
API.MIDDLEWARE_INSERT_TARGET_NOT_FOUND	chain.insertBefore/insertAfter
API.SHUTDOWN_TIMEOUT	SuaveApp.stop(timeoutMs) exceeds budget
API.SERVER_START_FAILED	serverFactory throws during start

Design notes vs upstream

• SuaveApp is dependency-injected — no internal new.
• AppBuilder.tenant(resolver) actually wires createTenantMiddleware into the chain (upstream silently dropped).
• One opt-in RequestContext AsyncLocalStorage instead of three.
• No global singletons (globalApp, getGlobalApp, etc.).
• CORS only exposes X-RateLimit-* when withRateLimitHeaders: true.
• MiddlewareChain.insertBefore/insertAfter raise on missing target.
• Error handler passes the full SuaveplanError statusCode through (no closed-enum cast).
• Configurable health routes.
• YAML / TOML config formats removed (upstream advertised, never worked).