skills/docs/api-stack/api/README.md

api

API orchestration, plugin lifecycle, routing, workers, and tenant resolution.

Packages in api

90 packages.

Package	Description
@suaveplan/api	The thin Hono-based application orchestrator for the Suaveplan API stack. Composes the four sibling packages — @suaveplan/api-plugin, @suaveplan/api-tenant…
@suaveplan/api-2pc	Two-phase commit coordinator for the Suaveplan API plugin system. Drives Postgres PREPARE TRANSACTION / COMMIT PREPARED / ROLLBACK PREPARED across registered p…
@suaveplan/api-audit-file	File-rotating, HMAC-signed audit sink for @suaveplan/api-host. Implements RequestAuditSink from @suaveplan/api-host/request-pipeline: writes one JSON lin…
@suaveplan/api-audit-stdout	Stdout audit sink for @suaveplan/api-host. Writes JSON-per-line audit records to a LineWriter (default process.stdout) with an HMAC-SHA-256 signature app…
@suaveplan/api-auth	$2 for the Suaveplan API plugin system. Defines the abstract session-resolver shape (Request → Principal | null) used by the host on every request, plus…
@suaveplan/api-auth-anonymous	Stage-4 trivial session resolver for @suaveplan/api. Always returns null for every request. Use this as the tail of resolver chains for public endpoints, a…
@suaveplan/api-auth-bearer-static	Stage-4 service-to-service SessionResolver adapter for the @suaveplan/api plugin system. Matches an inbound Authorization: Bearer <token> header against…
@suaveplan/api-auth-better-auth	Stage-6 Better-Auth adapter for @suaveplan/api. Ships two independently-wireable capability surfaces — createBetterAuthSession (implements `auth.sessio…
@suaveplan/api-auth-jwt	Stage-4 concrete SessionResolver for the @suaveplan/api plugin system. Verifies a JWT presented on the Authorization: Bearer <jwt> header (or a configure…
@suaveplan/api-auth-provider	Abstract account-lifecycle contract for the Suaveplan API plugin system (contracts). This package is OPTIONAL: hosted-IdP deployments (Clerk, Auth0, Cognito) i…
@suaveplan/api-auth-rolled	Stage-8.12 rolled session-token resolver for @suaveplan/api. Issues RS256-signed JWTs with rotating kid slots, verifies tokens through the rotator's active…
@suaveplan/api-auth-static-principal	Fixed-Principal session resolver for the @suaveplan/api plugin system. Returns the configured Principal verbatim on every request — no token decoding, no…
@suaveplan/api-db-adapter	Stage-4 bridge from the @suaveplan/db engine adapters to the plugin AdminDatabaseLike / TenantScopedDatabaseLike surfaces exposed by `@suaveplan/api-type…
@suaveplan/api-db-sqlite-memory	Stage-5 in-memory SQLite database adapter for the @suaveplan/api plugin host testing kit. Wraps bun:sqlite (in :memory: mode by default, or a file path f…
@suaveplan/api-db-worker-proxy	Worker-side proxy for the api db capability. Marshals AdminDatabaseLike and TenantScopedDatabaseLike calls — including transactions and cursor streams —…
@suaveplan/api-events-in-memory	In-memory events bus adapter for the @suaveplan/api testing kit. Wraps @suaveplan/events' production EventBus with a per-topic recording layer so tests c…
@suaveplan/api-events-worker-proxy	Worker-tier proxy over a main-process @suaveplan/events EventBus.
@suaveplan/api-graphql	Stage-1 abstract GraphQL contract for the Suaveplan API plugin system.
@suaveplan/api-graphql-apollo	Stage-7 Apollo Server GraphQL engine adapter for the Suaveplan API plugin system. Implements the GraphqlEngine contract from @suaveplan/api-graphql and pas…
@suaveplan/api-graphql-ui-altair	Altair GraphQL UI plugin for the Suaveplan API plugin system. Structural sibling of @suaveplan/api-graphql-ui-graphiql.
@suaveplan/api-graphql-ui-graphiql	GraphiQL UI mount for the Suaveplan API plugin system. Stage 7 of the umbrella plan.
@suaveplan/api-graphql-yoga	Stage-7 GraphQL Yoga engine adapter. Default GraphQL engine for the Suaveplan API plugin system per design doc §10.5 — Bun-friendly, fastest for our usage…
@suaveplan/api-host	Host orchestration core for the Suaveplan API plugin system. Provides the stable error-code registry (HOST/PLUGIN/RELOAD/CAPABILITY/ADMIN/LEDGER), the author-facing definePlugin DX, the runtime CapabilityRegistry, the LifecycleDriver + ReloadDriver + PluginLedger + admin Hono sub-router, the ErrorBoundary, the §6 11-step RequestPipeline, the top-level createHost(config) entry point composing every internal driver, and the HostInstruments registry covering the §12.3 metric surface. The ./testing subpath is reserved for test utilities.
@suaveplan/api-jobs-worker-proxy	Bidirectional MessagePort proxy that lets a worker-isolated API plugin participate in the host's main-process job scheduler. The worker calls registerCron…
@suaveplan/api-lifecycle	Stage-1 contract package for the Suaveplan API plugin system: the plugin-lifecycle finite state machine definition, the legal-transition table, the side-effect…
@suaveplan/api-loader	Stage-1 contract package for the Suaveplan API plugin system.
@suaveplan/api-logger-worker-proxy	Stage-3 worker → main proxy for @suaveplan/logger. Lets a worker-isolated API plugin call a normal LoggerLike surface while the records cross a `MessagePor…
@suaveplan/api-manifest	Stage-1 contract package of the Suaveplan API plugin system: Zod schemas, parser, cross-field validators, dependency-graph resolver, capability resolver, and c…
@suaveplan/api-migrations	Database-agnostic migration runner for the Suaveplan API. Ships a narrow MigrationAdapter surface (six methods), three shipped adapters (surrealql, `postgr…
@suaveplan/api-openapi	OpenAPI 3.1 registry, typed RouteBuilder, schema registry, and document merger for the Suaveplan API. Single source of truth that wires into Hono via `OpenAP…
@suaveplan/api-openapi-ui-redoc	Stage-8 ReDoc UI adapter for the Suaveplan api-host. Mounts the ReDoc HTML shell at /docs/ui/redoc (or any caller-chosen path) via createRedocUiHandler and…
@suaveplan/api-openapi-ui-scalar	Scalar UI adapter for the Suaveplan OpenAPI plugin system.
@suaveplan/api-openapi-ui-swagger	Swagger UI adapter for the /docs/ui/swagger endpoint of the Suaveplan API plugin system (Stage 8.8). Returns a pure HTTP handler whose response is a `text/ht…
@suaveplan/api-plugin	Plugin-system foundation for the Suaveplan API. Universal — runs unchanged in Bun, Node, and the browser.
@suaveplan/api-plugin-audit	Hono plugin that wraps @suaveplan/audit-logging as a write-through audit trail for @suaveplan/api. Installs a global per-request audit middleware (method /…
@suaveplan/api-plugin-auth	Better-Auth-first authentication plugin for @suaveplan/api. The canonical exemplar of the 3-way plug-and-play contract every @suaveplan/api-plugin-* packag…
@suaveplan/api-plugin-campaigns	Campaigns + suppression + delivery-webhooks HTTP plugin for @suaveplan/api. Mounts the /campaigns, /suppression, and /webhooks route trees on a Hono `O…
@suaveplan/api-plugin-cms	Headless content-management primitives for @suaveplan/api. Ships an in-memory CmsEngine that manages flexible content models, content entries with a `draft…
@suaveplan/api-plugin-database	SurrealDB-backed database plugin for @suaveplan/api. Pools @suaveplan/surrealdb's SurrealAdapter (implementing @suaveplan/db's DatabaseAdapter), runs…
@suaveplan/api-plugin-event-bus	Typed event-bus plugin for @suaveplan/api. Wraps @suaveplan/events (pub/sub, async dispatch, interceptors, bounded-queue backpressure, idempotent listener…
@suaveplan/api-plugin-events	Event-management plugin for @suaveplan/api. Ships a SurrealDB-backed EventRepository + RsvpRepository pair, ten Hono OpenAPI routes (list / get / create…
@suaveplan/api-plugin-example	Reference plugin for the @suaveplan/api-host plugin system. The package is a load-bearing integration target, not a tutorial: every contract surface the host…
@suaveplan/api-plugin-export	Data-export plugin for @suaveplan/api. Turns any registered resource into a CSV (RFC 4180), JSON, or XLSX (SpreadsheetML XML) blob through three self-contain…
@suaveplan/api-plugin-file-upload	Multipart and chunked file-upload plugin for @suaveplan/api. Ships six OpenAPI-typed Hono routes, a pluggable storage + session-store contract, SHA-256 hash…
@suaveplan/api-plugin-graphql	GraphQL description + resolver-composition layer for @suaveplan/api. Server-tier — runs in Bun and Node.
@suaveplan/api-plugin-import	Tabular-data ingest plugin for @suaveplan/api. Parses CSV / JSON / TSV-XLSX payloads, applies declarative column mappings + per-field validation + computed f…
@suaveplan/api-plugin-notifications	SurrealDB-backed notifications + push plugin for @suaveplan/api. Ships a NotificationRepository + DeviceTokenRepository pair, an ApnService with a plug…
@suaveplan/api-plugin-payment	Payment-lifecycle plugin for @suaveplan/api. Wraps @suaveplan/payment + a caller-injected PaymentProvider (Stripe / Adyen / PayPal / Square / Mollie / cu…
@suaveplan/api-plugin-rate-limit	Rate-limit plugin for @suaveplan/api. Wraps @suaveplan/rate-limiter as a definePlugin descriptor exposing per-route + per-tenant configuration, parameter…
@suaveplan/api-plugin-search	Full-text search plugin for @suaveplan/api. Brings TF-weighted relevance scoring, four built-in text analyzers (standard, simple, whitespace, keyword…
@suaveplan/api-plugin-site	Multi-site / multi-domain management plugin for @suaveplan/api. Stores site records (name, slug, theme, settings, push config) in SurrealDB, resolves incom…
@suaveplan/api-plugin-sse	Server-Sent Events plugin for @suaveplan/api. Registers a typed sseService in the host ServiceRegistry, mounts a Hono streaming handler at `GET /sse/:cha…
@suaveplan/api-plugin-tenant	Multi-tenancy plugin for @suaveplan/api. Wraps @suaveplan/api-tenant's resolver chain (header / subdomain / domain / path / JWT / query / cookie) as a firs…
@suaveplan/api-plugin-user	User-profile CRUD plugin for @suaveplan/api. Mounts the canonical /users/me GET/PATCH/DELETE surface on top of @suaveplan/api-plugin-auth, registers a ty…
@suaveplan/api-plugin-vault	Per-user vault HTTP plugin for @suaveplan/api. Third instance of the 3-way plug-and-play contract every @suaveplan/api-plugin-* package follows: the plugin…
@suaveplan/api-plugin-webhook	Signed outbound webhook delivery plugin for @suaveplan/api. Wraps @suaveplan/webhook-client behind a definePlugin descriptor, registers a typed `webhookS…
@suaveplan/api-rate-limit	Per-route / per-principal / per-tenant / per-IP token-bucket rate-limit middleware for @suaveplan/api. Implements the RequestRateLimiter contract consumed…
@suaveplan/api-rbac	Scope + rule-based authorisation middleware for the Suaveplan API plugin system. Produces a framework-agnostic Middleware that consumes the resolved `Princip…
@suaveplan/api-router	Stage-1 contract package for the Suaveplan API plugin system.
@suaveplan/api-router-hono	Stage-4 concrete Hono router adapter for @suaveplan/api. Implements the abstract Router contract from @suaveplan/api-router on top of a Hono Hono insta…
@suaveplan/api-router-in-memory	Stage-5 in-memory router adapter for @suaveplan/api. Implements both the abstract Router contract from @suaveplan/api-router AND the PipelineRouter con…
@suaveplan/api-router-worker-bridge	Stage-3 HTTP bridge that marshals Fetch Request and Response objects across the worker boundary. Pairs a main-side dispatch with a worker- side handler o…
@suaveplan/api-saga	Saga orchestrator for the Suaveplan API plugin system. Drives manifest-declared multi-plugin workflows in declared order with reverse-order compensation on fai…
@suaveplan/api-sandbox-permissions	Permission model for sandboxed-tier API plugins. Centralises the permissions.fs[] / permissions.fetch[] allowlists, the permissions.budgets enforcement,…
@suaveplan/api-sandbox-vm	vm.Context-based sandbox host for Suaveplan API plugins running in the sandboxed tier. The package owns the vm.Context+frozen-globals half of the design do…
@suaveplan/api-sandbox-vm-host-bridge	Host-integration bridge that lets a VmSandboxHandle from @suaveplan/api-sandbox-vm install into @suaveplan/api-host as a first-class plugin.
@suaveplan/api-sandbox-wasm	Stage-8 WebAssembly sandbox host. Instantiates a sandboxed-tier plugin WASM module against a WASI snapshot preview1 implementation derived from the plugin's `P…
@suaveplan/api-sandbox-wasm-host-bridge	Host-integration layer that wraps a @suaveplan/api-sandbox-wasm WasmSandboxHandle as a @suaveplan/api-host PluginModule. Sandboxed-tier plugins compile…
@suaveplan/api-schemas	Shared Zod schemas describing Suaveplan API request/response shapes. The single source of truth for server plugins, React data hooks, and generated OpenAPI doc…
@suaveplan/api-secrets	Abstract Secrets contract for the Suaveplan API plugin system — per-plugin secret access typed against manifest.secrets[], canonical redaction marker, frozen…
@suaveplan/api-secrets-bun	Stage-8 SecretsLike adapter backed by Bun.secrets (macOS Keychain, Linux libsecret, Windows Credential Manager) with per-plugin allow-list enforcement, OS-…
@suaveplan/api-secrets-env	Stage-4 SecretsLike adapter backed by process.env / Bun.env with per-plugin allowed-keys enforcement.
@suaveplan/api-secrets-vault	Stage-8 SecretsLike adapter backed by @suaveplan/vault. The vault is passed in already unlocked by the host's startup sequence; the adapter never sees the…
@suaveplan/api-secrets-worker-proxy	Stage-3 worker → main SecretsLike proxy for the API plugin system.
@suaveplan/api-sse	Abstract Server-Sent Events contracts for @suaveplan/api. Stage-1 contract package: defines the engine-side SseConnection, SseBroker, ReplayBuffer (Las…
@suaveplan/api-sse-bun	Bun.serve-backed Server-Sent Events engine for the @suaveplan/api plugin system. Implements the abstract @suaveplan/api-sse contract and passes `runSseEn…
@suaveplan/api-tenant	Multi-tenant resolution + scoping for the Suaveplan API. Server-tier — runs on Bun and Node, depends on hono and node:async_hooks.
@suaveplan/api-tenant-provider	Abstract TenantProvider contract for the Suaveplan API plugin system. Enumerates the universe of tenants known to a host so per-tenant cron / queued jobs (ma…
@suaveplan/api-tenant-provider-memory	In-memory reference implementation of the @suaveplan/api-tenant-provider TenantProvider contract. Backed by an insertion-ordered `Map<TenantId, TenantRecor…
@suaveplan/api-tenant-resolver-header	Stage-8 tenant resolver. Implements the TenantResolver contract from @suaveplan/api-types/tenant-resolver by reading the tenant identifier from a configura…
@suaveplan/api-tenant-resolver-jwt	Stage-4 tenant resolver for the Suaveplan API plugin system. Reads the already-resolved Principal.tenantId (attached by an earlier api-auth-* chain step) a…
@suaveplan/api-tenant-resolver-subdomain	Stage-8 tenant resolver for the Suaveplan API plugin system. Reads the inbound Host header (and optionally a CIDR-trusted X-Forwarded-Host), strips a confi…
@suaveplan/api-types	Root contract-types package for the Suaveplan API plugin system. Defines every cross-cutting type the foundation packages (api-manifest, api-router, `api-h…
@suaveplan/api-worker-host	Worker-side runtime that hosts exactly one Suaveplan API plugin inside an isolated Worker thread. The main-process counterpart is @suaveplan/api-host; this…
@suaveplan/api-worker-rpc	MessagePort-based RPC protocol for worker-isolated API plugins. Provides the shared protocol — Zod-validated wire frames, monotonic correlation ids, AbortSigna…
@suaveplan/api-ws	Abstract WebSocket engine contract for the Suaveplan API foundation — Connection, ConnectionRegistry, SubscriptionBus, WsBroker, reconnect-token envelope, backpressure + heartbeat policies, cross-tenant capability gate, and a runWsEngineConformance harness. Stage-1 contracts only; concrete engines (api-ws-bun) and brokers (api-ws-broker-redis / -in-memory) plug behind these interfaces.
@suaveplan/api-ws-broker-in-memory	Single-host in-process implementation of the @suaveplan/api-ws WsBroker contract. Suitable for production single-host deployments AND as the default broker…
@suaveplan/api-ws-broker-redis	Cross-host Redis pub/sub broker for @suaveplan/api-ws and @suaveplan/api-sse.
@suaveplan/api-ws-bun	Bun.serve-backed WebSocket engine for the @suaveplan/api-ws Stage-1 abstract contract. The engine composes the per-connection handshake pipeline, registry, s…
@suaveplan/wasm-compiler-javy	TS->WASM compiler closing Stage-8 gate 2.8. Thin orchestrator around Bun.build (bundle) + an injected WASI-stdio ABI shim + Javy v8.1.1 (JS->WASM) +…