@owlmeans/server-api

Fastify-based HTTP/WebSocket server with handler wrappers for the OwlMeans module system.

Overview

• handleBody, handleParams, handleRequest wrap business logic with context injection and error handling
• Built on Fastify — registered modules become Fastify routes automatically
• createApiServer / appendApiServer initialize the HTTP server in a context
• Not typically used directly — import handlers from @owlmeans/server-app

Installation

bun add @owlmeans/server-api

Usage

Handler functions called via elevate() in modules:

import { handleBody, handleParams, handleRequest } from '@owlmeans/server-app'

// Body handler: receives parsed + validated body as first arg
export const create = handleBody<CreateProject>(async (payload, context, req) => {
  const ctx = context as Context
  return await ctx.project().create({ ...payload, entityId: req.auth!.entityId })
})

// Params handler: receives validated URL params as first arg
export const get = handleParams<{ id: string }>(async (params, context, req) => {
  return await (context as Context).project().get(params.id)
})

// Request handler: receives the full AbstractRequest
export const health = handleRequest(async (req, context) => {
  return { status: 'ok' }
})

API

handleBody<T>(handler): RefedModuleHandler

Wraps a handler that receives the validated request body as the first argument.

handler: (payload: T, ctx: Context, req: AbstractRequest) => Promise<any>

handleParams<T>(handler): RefedModuleHandler

Wraps a handler that receives the validated URL params as the first argument.

handler: (payload: T, ctx: Context, req: AbstractRequest) => Promise<any>

handleRequest(handler): RefedModuleHandler

Wraps a handler that receives the full request object.

handler: (req: AbstractRequest, ctx: Context, res?: AbstractResponse) => Promise<any>

handleIntermediate(handler): RefedModuleHandler

Wraps middleware-layer handlers that do not return a final response.

extractUploadedFile(req, fieldName): UploadedFile | null

Extract a multipart-uploaded file from the request.

Related Packages

• @owlmeans/server-app — re-exports all handlers; preferred import point
• @owlmeans/server-module — elevate() attaches handlers to modules
• @owlmeans/server-socket — WebSocket handleConnection counterpart

Agent guidance

This package ships embedded Claude Code skills and GitHub Copilot instructions under agent-meta/. After installing your @owlmeans/* packages, run the OwlMeans agent-skills installer to place them into your project's native locations (.claude/skills/ and .github/instructions/):

npx @owlmeans/agent-skills

The embedded files are version-matched to this package release. Do not edit them directly — they are regenerated on each publish. To contribute guidance edits, open a PR against the source monorepo.