@venturekit/runtime 0.0.0-dev.20260308002709 → 0.0.0-dev.20260311071358

package/README.md

@@ -0,0 +1,136 @@
+# @venturekit/runtime
+
+> **Warning:** This package is in active development and not production-ready. APIs may change without notice.
+
+Runtime utilities for [VentureKit](https://venturekit.dev) Lambda functions — handlers, context, middleware, logging, errors, and WebSocket support.
+
+## Installation
+
+```bash
+npm install @venturekit/runtime@dev
+```
+
+## Overview
+
+`@venturekit/runtime` provides everything needed to write VentureKit route handlers:
+
+- **Unified handler** that adapts to context (public vs authenticated)
+- **Request context** with typed user, tenant, and request metadata
+- **Response helpers** (`success`, `created`, `noContent`, `error`, `redirect`)
+- **Structured errors** with HTTP status codes
+- **Composable middleware** (logging, CORS, timeout, error boundary)
+- **Structured logging** via Pino
+- **WebSocket connection store** for real-time applications
+
+## Handler
+
+The `handler()` function is the primary API. It wraps your business logic with auth checks, body parsing, status code detection, middleware, and error handling.
+
+```typescript
+import { handler } from '@venturekit/runtime';
+
+// Public endpoint (no scopes = no auth)
+export const main = handler(async (_body, ctx, logger) => {
+  logger.info('Health check');
+  return { status: 'healthy', timestamp: ctx.timestamp.toISOString() };
+});
+
+// Authenticated endpoint (scopes = auth required)
+export const main = handler(async (body, ctx, logger) => {
+  return { id: '123', name: body.name };
+}, { scopes: ['api.write'] });
+```
+
+### Status Code Detection
+
+| HTTP Method | Default Status |
+|-------------|---------------|
+| `GET`, `PUT`, `PATCH` | `200 OK` |
+| `POST` | `201 Created` |
+| `DELETE` | `204 No Content` |
+
+Override with `{ status: 200 }` in the handler config.
+
+### Transactional Handlers
+
+```typescript
+export const main = handler(async (body, ctx, logger) => {
+  // ctx.tx is a database transaction — auto-commits on success, rolls back on error
+  await ctx.tx.query('INSERT INTO tasks (title) VALUES ($1)', [body.title]);
+  return { created: true };
+}, { scopes: ['tasks.write'], transactional: true });
+```
+
+## Context
+
+Every handler receives a `RequestContext`:
+
+```typescript
+interface RequestContext {
+  requestId: string;
+  timestamp: Date;
+  method: string;
+  path: string;
+  sourceIp: string;
+  userAgent: string;
+  user: UserContext | null;       // Populated for authenticated requests
+  tenant: TenantContext | null;   // Populated when @venturekit/tenancy is enabled
+  locale: string;
+  queryParams?: Record<string, string | undefined>;
+  tx?: unknown;                   // Database transaction (transactional handlers)
+  intentOutputs?: Record<string, unknown>; // Infrastructure intent outputs
+  rawEvent: APIGatewayProxyEventV2;
+}
+```
+
+## Errors
+
+Throw structured errors in your handlers — they are automatically serialized to JSON responses:
+
+```typescript
+import { NotFoundError, BadRequestError, ForbiddenError } from '@venturekit/runtime';
+
+throw new NotFoundError('Task', '123');     // 404
+throw new BadRequestError('Invalid input'); // 400
+throw new ForbiddenError();                 // 403
+```
+
+Available error classes: `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `ValidationError`, `RateLimitError`, `InternalError`, `ServiceUnavailableError`.
+
+## Middleware
+
+Compose middleware for cross-cutting concerns:
+
+```typescript
+import { compose, loggingMiddleware, corsMiddleware, timeoutMiddleware } from '@venturekit/runtime';
+
+export const main = handler(async (body, ctx, logger) => {
+  return { ok: true };
+}, {
+  middleware: [
+    corsMiddleware({ allowOrigins: ['*'], allowMethods: ['GET'], allowHeaders: ['*'], allowCredentials: false, maxAge: 3600 }),
+    timeoutMiddleware(5000),
+  ],
+});
+```
+
+## WebSocket
+
+For real-time applications, use the `connectionStore`:
+
+```typescript
+import { connectionStore } from '@venturekit/runtime';
+
+await connectionStore.save(connectionId);
+await connectionStore.authenticate(connectionId, { userId, email, tenantId });
+await connectionStore.sendToUser(domainName, stage, userId, data);
+await connectionStore.broadcast(domainName, stage, data);
+```
+
+## API Reference
+
+See the [API reference](https://venturekit.dev/api-reference/runtime) for full documentation.
+
+## License
+
+Apache-2.0 — see [LICENSE](../../LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venturekit/runtime",
-  "version": "0.0.0-dev.20260308002709",
+  "version": "0.0.0-dev.20260311071358",
   "description": "VentureKit runtime utilities - handlers, context, middleware, logging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -24,11 +24,11 @@
   ],
   "license": "Apache-2.0",
   "dependencies": {
-    "@venturekit/core": "0.0.0-dev.20260308002709",
+    "@venturekit/core": "0.0.0-dev.20260311071358",
     "pino": "^9.0.0"
   },
   "peerDependencies": {
-    "@venturekit/data": "0.0.0-dev.20260308002709",
+    "@venturekit/data": "0.0.0-dev.20260311071358",
     "@aws-sdk/client-dynamodb": "^3.500.0",
     "@aws-sdk/lib-dynamodb": "^3.500.0",
     "@aws-sdk/client-apigatewaymanagementapi": "^3.500.0"
@@ -48,7 +48,7 @@
     }
   },
   "devDependencies": {
-    "@venturekit/data": "0.0.0-dev.20260308002709",
+    "@venturekit/data": "0.0.0-dev.20260311071358",
     "@types/aws-lambda": "^8.10.131",
     "@types/node": "^20.10.0",
     "typescript": "^5.3.0"