@venturekit/runtime API

Functions

handler(fn, config?)

Creates a unified Lambda handler that wraps your business logic with auth, body parsing, status codes, middleware, and error handling.

function handler<TBody = unknown, TResult = unknown>(
  fn: HandlerFn<TBody, TResult>,
  config?: HandlerConfig
): (event: APIGatewayProxyEventV2, context: Context) => Promise<APIGatewayProxyResultV2>

buildContext(event, options)

Builds a RequestContext from an API Gateway event.

function buildContext(
  event: APIGatewayProxyEventV2,
  options: { supportedLocales: string[]; defaultLocale: string }
): RequestContext

extractUserContext(event)

Extracts user information from JWT claims in the API Gateway event.

function extractUserContext(event: APIGatewayProxyEventV2): UserContext | null

extractLocale(event, supportedLocales, defaultLocale)

Extracts the locale from the Accept-Language header.

function extractLocale(event: APIGatewayProxyEventV2, supported: string[], fallback: string): string

Response Helpers

Function	Status	Description
success(data, meta?)	200	Success response
created(data, meta?)	201	Created response
noContent(meta?)	204	No content response
error(statusCode, body)	*	Custom error response
errorResponse(error, meta?)	*	Format a VentureError
redirect(url, statusCode?)	301/302	Redirect response

Middleware

Function	Description
compose(middlewares)	Compose middleware into a single function
loggingMiddleware(logger)	Request/response logging with timing
corsMiddleware(options)	CORS headers and preflight handling
timeoutMiddleware(ms)	Request timeout enforcement
errorBoundaryMiddleware(handler)	Catch and format errors

Logger

Export	Description
Logger	Logger class
createLogger(config?)	Create a new logger instance
logger	Default logger instance

Types

HandlerFn<TBody, TResult>

type HandlerFn<TBody, TResult> = (
  body: TBody,
  ctx: RequestContext,
  logger: Logger
) => Promise<TResult>

HandlerConfig

interface HandlerConfig {
  scopes?: string[]
  status?: 200 | 201 | 204
  middleware?: Middleware[]
  logLevel?: 'debug' | 'info' | 'warn' | 'error'
  transactional?: boolean
}

RequestContext

interface RequestContext {
  requestId: string
  timestamp: Date
  method: string
  path: string
  sourceIp: string
  userAgent: string
  user: UserContext | null
  tenant: TenantContext | null
  locale: string
  queryParams?: Record<string, string | undefined>
  tx?: unknown
  intentOutputs?: Record<string, unknown>
  rawEvent: APIGatewayProxyEventV2
}

UserContext

interface UserContext {
  id: string
  email?: string
  scopes: string[]
  claims: Record<string, unknown>
}

TenantContext

interface TenantContext {
  id: string
  slug?: string
  metadata: Record<string, unknown>
}

Middleware

interface Middleware {
  name: string
  fn: MiddlewareFn
}

type MiddlewareFn = (
  ctx: RequestContext,
  next: () => Promise<APIGatewayProxyResultV2>
) => Promise<APIGatewayProxyResultV2>

Error Classes

Class	Status	Code
VentureError	500	Base class
BadRequestError	400	BAD_REQUEST
UnauthorizedError	401	UNAUTHORIZED
ForbiddenError	403	FORBIDDEN
NotFoundError	404	NOT_FOUND
ConflictError	409	CONFLICT
ValidationError	422	VALIDATION_ERROR
RateLimitError	429	RATE_LIMITED
InternalError	500	INTERNAL_ERROR
ServiceUnavailableError	503	SERVICE_UNAVAILABLE

isVentureError(error)

Type guard to check if an error is a VentureError.

function isVentureError(error: unknown): error is VentureError

WebSocket

connectionStore

Method	Description
save(connectionId)	Save a new connection (unauthenticated)
authenticate(connectionId, metadata)	Upgrade to authenticated
remove(connectionId)	Remove a connection
get(connectionId)	Get a connection record
getByUser(userId)	Get all connections for a user
getByTenant(tenantId)	Get all connections for a tenant
postToConnection(domain, stage, connId, data)	Send to one connection
sendToUser(domain, stage, userId, data)	Send to all user sessions
sendToTenant(domain, stage, tenantId, data)	Send to all tenant connections
broadcast(domain, stage, data)	Send to all connections