@mono-labs/dev 0.1.251

package/dist/websocket/index.d.ts

@@ -0,0 +1,20 @@
+import type { WebSocket, WebSocketServer } from 'ws';
+import { ActionRouter } from './action-router';
+import { ConnectionRegistry } from './connection-registry';
+import type { SocketAdapterConfig } from './types';
+export type { ConnectionId, PostToConnectionFn, SocketAdapterConfig } from './types';
+export { ConnectionRegistry } from './connection-registry';
+export { LocalGatewayClient } from './local-gateway-client';
+export { ActionRouter } from './action-router';
+/**
+ * Attaches a full socket adapter to a WebSocketServer instance.
+ * Maps 1:1 to each API Gateway WebSocket event so local dev
+ * behaves identically to the deployed system.
+ */
+export declare function attachSocketAdapter(wss: WebSocketServer, config?: SocketAdapterConfig): {
+    postToConnection: import("./types").PostToConnectionFn;
+    connectionRegistry: ConnectionRegistry;
+    actionRouter: ActionRouter;
+    getConnectionId: (ws: WebSocket) => string | undefined;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/websocket/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/websocket/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,IAAI,CAAA;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAG1D,OAAO,KAAK,EAAgB,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAEhE,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9C;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,mBAAmB;;;;0BA6H9D,SAAS;EAEhC"}

package/dist/websocket/index.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionRouter = exports.LocalGatewayClient = exports.ConnectionRegistry = void 0;
+exports.attachSocketAdapter = attachSocketAdapter;
+const action_router_1 = require("./action-router");
+const connection_registry_1 = require("./connection-registry");
+const event_synthesizer_1 = require("./event-synthesizer");
+const local_gateway_client_1 = require("./local-gateway-client");
+var connection_registry_2 = require("./connection-registry");
+Object.defineProperty(exports, "ConnectionRegistry", { enumerable: true, get: function () { return connection_registry_2.ConnectionRegistry; } });
+var local_gateway_client_2 = require("./local-gateway-client");
+Object.defineProperty(exports, "LocalGatewayClient", { enumerable: true, get: function () { return local_gateway_client_2.LocalGatewayClient; } });
+var action_router_2 = require("./action-router");
+Object.defineProperty(exports, "ActionRouter", { enumerable: true, get: function () { return action_router_2.ActionRouter; } });
+/**
+ * Attaches a full socket adapter to a WebSocketServer instance.
+ * Maps 1:1 to each API Gateway WebSocket event so local dev
+ * behaves identically to the deployed system.
+ */
+function attachSocketAdapter(wss, config) {
+    const debug = config?.debug ?? false;
+    const domainName = config?.domainName ?? 'localhost';
+    const stage = config?.stage ?? 'local';
+    const connectionRegistry = new connection_registry_1.ConnectionRegistry();
+    const gatewayClient = new local_gateway_client_1.LocalGatewayClient(connectionRegistry);
+    const postToConnection = gatewayClient.asFunction();
+    const actionRouter = new action_router_1.ActionRouter();
+    // Register consumer-provided routes
+    if (config?.routes) {
+        for (const [action, handler] of Object.entries(config.routes)) {
+            actionRouter.addRoute(action, handler);
+        }
+    }
+    // $default handler for unknown actions
+    if (config?.defaultHandler) {
+        actionRouter.setDefaultHandler(config.defaultHandler);
+    }
+    else {
+        actionRouter.setDefaultHandler(async (body, ctx) => {
+            let action = 'unknown';
+            try {
+                action = JSON.parse(body).action ?? 'unknown';
+            }
+            catch { }
+            return {
+                statusCode: 400,
+                body: JSON.stringify({ error: `Unknown action: ${action}` }),
+            };
+        });
+    }
+    // Use consumer-provided handlers or sensible defaults
+    const connectHandler = config?.connectHandler ?? (async () => ({
+        response: { statusCode: 200 },
+        userContext: undefined,
+    }));
+    const disconnectHandler = config?.disconnectHandler ?? (async () => { });
+    // Reverse lookup: WebSocket → connectionId
+    const wsToConnectionId = new WeakMap();
+    wss.on('connection', async (ws, req) => {
+        // 1. Extract token from query string
+        const url = new URL(req.url ?? '', `http://${req.headers.host ?? 'localhost'}`);
+        const token = url.searchParams.get('token') ?? undefined;
+        // 2. Register connection and assign connectionId
+        const connectionId = connectionRegistry.register(ws);
+        wsToConnectionId.set(ws, connectionId);
+        if (debug)
+            console.log(`[socket-adapter] $connect connectionId=${connectionId}`);
+        if (debug)
+            console.log(`[socket-adapter] token ${token ? 'present' : 'MISSING'}`);
+        // 3. Authenticate via connectHandler
+        const { response, userContext } = await connectHandler(connectionId, { token });
+        if (debug)
+            console.log(`[socket-adapter] connectHandler result:`, response);
+        if (debug && userContext) {
+            console.log(`[socket-adapter] authenticated userId=${userContext.userId} orgId=${userContext.organizationId}`);
+        }
+        // 4. Reject if connectHandler returns non-200
+        if (response.statusCode !== 200) {
+            if (debug)
+                console.log(`[socket-adapter] rejected connectionId=${connectionId} status=${response.statusCode}`);
+            ws.close(1008, 'Authentication failed');
+            connectionRegistry.unregister(connectionId);
+            wsToConnectionId.delete(ws);
+            return;
+        }
+        // 5. Store user context in the registry (if provided)
+        if (userContext) {
+            connectionRegistry.setUserContext(connectionId, userContext);
+        }
+        // 6. Send welcome message to client
+        const welcomeMessage = { type: 'connected', connectionId };
+        if (userContext)
+            welcomeMessage.userId = userContext.userId;
+        ws.send(JSON.stringify(welcomeMessage));
+        if (debug)
+            console.log(`[socket-adapter] welcome sent to ${connectionId}${userContext ? ` userId=${userContext.userId}` : ''}`);
+        // 7. Route incoming messages through ActionRouter
+        ws.on('message', async (raw) => {
+            const rawBody = raw.toString();
+            if (debug)
+                console.log(`[socket-adapter] message from ${connectionId}:`, rawBody);
+            const requestContext = (0, event_synthesizer_1.buildRequestContext)(connectionId, '$default', 'MESSAGE', {
+                domainName,
+                stage,
+            });
+            const resolvedUserContext = userContext ?? connectionRegistry.getUserContext(connectionId) ?? {
+                userId: 'anonymous',
+                organizationId: 'anonymous',
+            };
+            const result = await actionRouter.route(connectionId, rawBody, postToConnection, requestContext, resolvedUserContext);
+            // Send the handler result back to the sender
+            if (result.body) {
+                ws.send(result.body);
+            }
+        });
+        // 8. Handle disconnect
+        ws.on('close', async (code, reason) => {
+            if (debug) {
+                console.log(`[socket-adapter] $disconnect connectionId=${connectionId} code=${code} reason=${reason.toString()}`);
+            }
+            await disconnectHandler(connectionId);
+            connectionRegistry.unregister(connectionId);
+            wsToConnectionId.delete(ws);
+        });
+    });
+    return {
+        postToConnection,
+        connectionRegistry,
+        actionRouter,
+        getConnectionId: (ws) => wsToConnectionId.get(ws),
+    };
+}

package/dist/websocket/local-gateway-client.d.ts

@@ -0,0 +1,15 @@
+import type { ConnectionRegistry } from './connection-registry';
+import type { ConnectionId, PostToConnectionFn } from './types';
+/**
+ * Local replacement for @aws-sdk/client-apigatewaymanagementapi.
+ * Looks up the WebSocket in ConnectionRegistry and sends data directly.
+ */
+export declare class LocalGatewayClient {
+    private registry;
+    constructor(registry: ConnectionRegistry);
+    /** Send data to a specific connection. Throws GoneException (410) if not found. */
+    postToConnection(connectionId: ConnectionId, data: unknown): Promise<void>;
+    /** Returns a bound PostToConnectionFn for dependency injection */
+    asFunction(): PostToConnectionFn;
+}
+//# sourceMappingURL=local-gateway-client.d.ts.map

package/dist/websocket/local-gateway-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-gateway-client.d.ts","sourceRoot":"","sources":["../../src/websocket/local-gateway-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAE/D;;;GAGG;AACH,qBAAa,kBAAkB;IAClB,OAAO,CAAC,QAAQ;gBAAR,QAAQ,EAAE,kBAAkB;IAEhD,mFAAmF;IAC7E,gBAAgB,CAAC,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAchF,kEAAkE;IAClE,UAAU,IAAI,kBAAkB;CAGhC"}

package/dist/websocket/local-gateway-client.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalGatewayClient = void 0;
+const ws_1 = require("ws");
+/**
+ * Local replacement for @aws-sdk/client-apigatewaymanagementapi.
+ * Looks up the WebSocket in ConnectionRegistry and sends data directly.
+ */
+class LocalGatewayClient {
+    registry;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    /** Send data to a specific connection. Throws GoneException (410) if not found. */
+    async postToConnection(connectionId, data) {
+        const ws = this.registry.get(connectionId);
+        if (!ws || ws.readyState !== ws_1.WebSocket.OPEN) {
+            const error = new Error(`GoneException: Connection ${connectionId} is no longer available`);
+            error.statusCode = 410;
+            error.name = 'GoneException';
+            throw error;
+        }
+        const payload = typeof data === 'string' ? data : JSON.stringify(data);
+        ws.send(payload);
+    }
+    /** Returns a bound PostToConnectionFn for dependency injection */
+    asFunction() {
+        return this.postToConnection.bind(this);
+    }
+}
+exports.LocalGatewayClient = LocalGatewayClient;

package/dist/websocket/types.d.ts

@@ -0,0 +1,55 @@
+/** User context attached to a WebSocket connection */
+export interface WebSocketUserContext {
+    userId: string;
+    organizationId: string;
+    [key: string]: unknown;
+}
+/** Unique identifier for a WebSocket connection (mirrors API Gateway connectionId) */
+export type ConnectionId = string;
+/** Function signature for sending data to a connection (replaces PostToConnectionCommand) */
+export type PostToConnectionFn = (connectionId: ConnectionId, data: unknown) => Promise<void>;
+/** Synthesized equivalent of event.requestContext for local dev */
+export interface LocalRequestContext {
+    connectionId: ConnectionId;
+    domainName: string;
+    stage: string;
+    routeKey: string;
+    eventType: 'CONNECT' | 'DISCONNECT' | 'MESSAGE';
+}
+/** Context passed to action handlers */
+export interface ActionHandlerContext {
+    connectionId: ConnectionId;
+    requestContext: LocalRequestContext;
+    postToConnection: PostToConnectionFn;
+    userContext: WebSocketUserContext;
+}
+/** Result returned from an action handler */
+export interface ActionHandlerResult {
+    statusCode: number;
+    body?: string;
+}
+/** Handler function for a routed action */
+export type ActionHandler = (body: string, ctx: ActionHandlerContext) => Promise<ActionHandlerResult>;
+/** Handler called on $connect — returns response + optional user context */
+export type ConnectHandlerFn = (connectionId: ConnectionId, params: {
+    token?: string;
+}) => Promise<{
+    response: {
+        statusCode: number;
+        body?: string;
+    };
+    userContext?: WebSocketUserContext;
+}>;
+/** Handler called on $disconnect */
+export type DisconnectHandlerFn = (connectionId: ConnectionId) => Promise<void>;
+/** Configuration for the socket adapter */
+export interface SocketAdapterConfig {
+    domainName?: string;
+    stage?: string;
+    debug?: boolean;
+    connectHandler?: ConnectHandlerFn;
+    disconnectHandler?: DisconnectHandlerFn;
+    routes?: Record<string, ActionHandler>;
+    defaultHandler?: ActionHandler;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/websocket/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/websocket/types.ts"],"names":[],"mappings":"AAEA,sDAAsD;AACtD,MAAM,WAAW,oBAAoB;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,cAAc,EAAE,MAAM,CAAA;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACtB;AAED,sFAAsF;AACtF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAA;AAEjC,6FAA6F;AAC7F,MAAM,MAAM,kBAAkB,GAAG,CAAC,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAE7F,mEAAmE;AACnE,MAAM,WAAW,mBAAmB;IACnC,YAAY,EAAE,YAAY,CAAA;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAAA;CAC/C;AAED,wCAAwC;AACxC,MAAM,WAAW,oBAAoB;IACpC,YAAY,EAAE,YAAY,CAAA;IAC1B,cAAc,EAAE,mBAAmB,CAAA;IACnC,gBAAgB,EAAE,kBAAkB,CAAA;IACpC,WAAW,EAAE,oBAAoB,CAAA;CACjC;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IACnC,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;CACb;AAED,2CAA2C;AAC3C,MAAM,MAAM,aAAa,GAAG,CAC3B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,oBAAoB,KACrB,OAAO,CAAC,mBAAmB,CAAC,CAAA;AAEjC,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG,CAC9B,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,KACtB,OAAO,CAAC;IACZ,QAAQ,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/C,WAAW,CAAC,EAAE,oBAAoB,CAAA;CAClC,CAAC,CAAA;AAEF,oCAAoC;AACpC,MAAM,MAAM,mBAAmB,GAAG,CAAC,YAAY,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAE/E,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IACnC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,cAAc,CAAC,EAAE,gBAAgB,CAAA;IACjC,iBAAiB,CAAC,EAAE,mBAAmB,CAAA;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACtC,cAAc,CAAC,EAAE,aAAa,CAAA;CAC9B"}

package/dist/websocket/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@mono-labs/dev",
+  "version": "0.1.251",
+  "type": "commonjs",
+  "description": "Local development server and WebSocket adapter for mono-labs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "deploy": "tsc && npm publish --access public --registry https://registry.npmjs.org/",
+    "release:patch": "npm version patch -m \"chore: release %s\" && npm publish --access public",
+    "release:minor": "npm version minor -m \"chore: release %s\" && npm publish --access public",
+    "release:major": "npm version major -m \"chore: release %s\" && npm publish --access public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^4.21.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/node": "^25.1.0",
+    "@types/ws": "^8.5.13",
+    "aws-lambda": "^1.0.7",
+    "@types/aws-lambda": "^8.10.145",
+    "typescript": "^5.9.3"
+  }
+}

package/src/aws-event-synthesis/index.ts

@@ -0,0 +1,99 @@
+import type { Context as LambdaContext } from 'aws-lambda'
+import type { Response } from 'express'
+
+// --- Header utilities ---
+
+/** Flatten Node.js IncomingHttpHeaders to Record<string, string> */
+export function flattenHeaders(
+	headers: Record<string, string | string[] | undefined>
+): Record<string, string> {
+	const flat: Record<string, string> = {}
+	for (const [key, value] of Object.entries(headers)) {
+		if (typeof value === 'string') flat[key] = value
+		else if (Array.isArray(value)) flat[key] = value.join(', ')
+	}
+	return flat
+}
+
+/** Serialize a request body to string (passthrough if already string, JSON.stringify if object) */
+export function serializeBody(body: unknown): string | null {
+	if (body === undefined || body === null) return null
+	if (typeof body === 'string') return body
+	return JSON.stringify(body)
+}
+
+/** Convert Express parsed query to Record<string, string | undefined> */
+export function extractQueryParams(
+	query: Record<string, unknown>
+): Record<string, string | undefined> {
+	const params: Record<string, string | undefined> = {}
+	for (const [key, value] of Object.entries(query)) {
+		if (typeof value === 'string') params[key] = value
+		else if (value !== undefined) params[key] = String(value)
+	}
+	return params
+}
+
+/** Split a URL into path and raw query string */
+export function splitUrl(originalUrl: string): { path: string; queryString: string } {
+	const qIndex = originalUrl.indexOf('?')
+	if (qIndex === -1) return { path: originalUrl, queryString: '' }
+	return {
+		path: originalUrl.slice(0, qIndex),
+		queryString: originalUrl.slice(qIndex + 1),
+	}
+}
+
+// --- Mock Lambda context ---
+
+/** Generate a local request ID */
+export function generateRequestId(): string {
+	return `local-${Date.now()}`
+}
+
+/** Create a minimal mock Lambda Context */
+export function createMockLambdaContext(functionName?: string): LambdaContext {
+	const name = functionName ?? 'local-handler'
+	return {
+		callbackWaitsForEmptyEventLoop: true,
+		functionName: name,
+		functionVersion: '$LATEST',
+		invokedFunctionArn: `arn:aws:lambda:us-east-1:000000000000:function:${name}`,
+		memoryLimitInMB: '128',
+		awsRequestId: generateRequestId(),
+		logGroupName: `/aws/lambda/${name}`,
+		logStreamName: 'local',
+		getRemainingTimeInMillis: () => 30_000,
+		done: () => {},
+		fail: () => {},
+		succeed: () => {},
+	}
+}
+
+// --- Result -> Express response ---
+
+/** Send a Lambda-style result (API Gateway V2 or ALB) back through Express */
+export function sendLambdaResult(
+	res: Response,
+	result: {
+		statusCode?: number
+		headers?: Record<string, any>
+		body?: string
+		isBase64Encoded?: boolean
+	}
+): void {
+	const statusCode = result.statusCode ?? 200
+
+	if (result.headers) {
+		for (const [key, value] of Object.entries(result.headers)) {
+			res.setHeader(key, value)
+		}
+	}
+
+	if (result.isBase64Encoded && result.body) {
+		const buffer = Buffer.from(result.body, 'base64')
+		res.status(statusCode).send(buffer)
+	} else {
+		res.status(statusCode).send(result.body ?? '')
+	}
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+// Core
+export { LocalServer } from './local-server'
+export type { ApiGatewayHandler, ALBHandler, LocalServerConfig } from './local-server/types'
+
+// WebSocket
+export { attachSocketAdapter } from './websocket'
+export { ConnectionRegistry } from './websocket/connection-registry'
+export { ActionRouter } from './websocket/action-router'
+export { LocalGatewayClient } from './websocket/local-gateway-client'
+export type {
+	ConnectionId,
+	PostToConnectionFn,
+	SocketAdapterConfig,
+	ConnectHandlerFn,
+	DisconnectHandlerFn,
+	ActionHandler,
+	ActionHandlerContext,
+	ActionHandlerResult,
+	LocalRequestContext,
+	WebSocketUserContext,
+} from './websocket/types'

package/src/local-server/event-synthesizer.ts

@@ -0,0 +1,71 @@
+import type { Request } from 'express'
+import type { APIGatewayProxyEventV2, ALBEvent } from 'aws-lambda'
+
+import {
+	flattenHeaders,
+	serializeBody,
+	extractQueryParams,
+	splitUrl,
+	generateRequestId,
+} from '../aws-event-synthesis'
+
+/** Synthesize an API Gateway V2 event from an Express request */
+export function synthesizeApiGatewayEvent(req: Request): APIGatewayProxyEventV2 {
+	const headers = flattenHeaders(req.headers)
+	const body = serializeBody(req.body)
+	const queryParams = extractQueryParams(req.query as Record<string, unknown>)
+	const { path, queryString } = splitUrl(req.originalUrl)
+	const requestId = generateRequestId()
+	const now = Date.now()
+
+	return {
+		version: '2.0',
+		routeKey: `$default`,
+		rawPath: path,
+		rawQueryString: queryString,
+		headers,
+		queryStringParameters: Object.keys(queryParams).length > 0 ? queryParams as Record<string, string> : undefined,
+		requestContext: {
+			accountId: 'local',
+			apiId: 'local',
+			domainName: req.hostname ?? 'localhost',
+			domainPrefix: 'local',
+			http: {
+				method: req.method,
+				path,
+				protocol: req.protocol ?? 'HTTP/1.1',
+				sourceIp: req.ip ?? '127.0.0.1',
+				userAgent: req.headers['user-agent'] ?? '',
+			},
+			requestId,
+			routeKey: '$default',
+			stage: 'local',
+			time: new Date(now).toISOString(),
+			timeEpoch: now,
+		},
+		body: body ?? undefined,
+		isBase64Encoded: false,
+	}
+}
+
+/** Synthesize an ALB event from an Express request */
+export function synthesizeALBEvent(req: Request): ALBEvent {
+	const headers = flattenHeaders(req.headers)
+	const body = serializeBody(req.body)
+	const queryParams = extractQueryParams(req.query as Record<string, unknown>)
+	const { path } = splitUrl(req.originalUrl)
+
+	return {
+		requestContext: {
+			elb: {
+				targetGroupArn: 'arn:aws:elasticloadbalancing:us-east-1:000000000000:targetgroup/local/local',
+			},
+		},
+		httpMethod: req.method,
+		path,
+		headers,
+		queryStringParameters: queryParams as Record<string, string | undefined>,
+		body: body ?? '',
+		isBase64Encoded: false,
+	}
+}

package/src/local-server/index.ts

@@ -0,0 +1,94 @@
+import http from 'node:http'
+
+import express from 'express'
+import cors from 'cors'
+import { WebSocketServer } from 'ws'
+
+import { createMockLambdaContext, sendLambdaResult } from '../aws-event-synthesis'
+import { synthesizeApiGatewayEvent, synthesizeALBEvent } from './event-synthesizer'
+
+import type { attachSocketAdapter } from '../websocket'
+import type { SocketAdapterConfig } from '../websocket/types'
+import type {
+	ApiGatewayHandler,
+	ALBHandler,
+	LambdaOptionsApiGateway,
+	LambdaOptionsALB,
+	LocalServerConfig,
+} from './types'
+
+export type { ApiGatewayHandler, ALBHandler, LocalServerConfig } from './types'
+
+export class LocalServer {
+	readonly app: express.Express
+	private httpServer: http.Server
+	private config: LocalServerConfig
+
+	constructor(config?: LocalServerConfig) {
+		this.config = config ?? {}
+		this.app = express()
+
+		this.app.use(express.json())
+		this.app.use(cors())
+
+		this.app.get('/', (_req, res) => {
+			res.send('Hello from Express HTTP Server')
+		})
+
+		this.httpServer = http.createServer(this.app)
+	}
+
+	// --- Type-safe overloads ---
+
+	lambda(path: string, handler: ApiGatewayHandler): this
+	lambda(path: string, handler: ApiGatewayHandler, options: LambdaOptionsApiGateway): this
+	lambda(path: string, handler: ALBHandler, options: LambdaOptionsALB): this
+	lambda(
+		path: string,
+		handler: ApiGatewayHandler | ALBHandler,
+		options?: LambdaOptionsApiGateway | LambdaOptionsALB,
+	): this {
+		const eventType = options?.eventType ?? 'api-gateway'
+
+		this.app.use(path, async (req: express.Request, res: express.Response) => {
+			try {
+				const context = createMockLambdaContext()
+
+				if (eventType === 'alb') {
+					const event = synthesizeALBEvent(req)
+					const result = await (handler as ALBHandler)(event, context)
+					sendLambdaResult(res, result)
+				} else {
+					const event = synthesizeApiGatewayEvent(req)
+					const result = await (handler as ApiGatewayHandler)(event, context)
+					sendLambdaResult(res, result ?? {})
+				}
+			} catch (err) {
+				console.error(`[LocalServer] Error handling ${req.method} ${req.originalUrl}:`, err)
+				if (!res.headersSent) {
+					res.status(500).json({ error: 'Internal Server Error' })
+				}
+			}
+		})
+
+		return this
+	}
+
+	attachSocket(
+		adapterFn: typeof attachSocketAdapter,
+		config?: SocketAdapterConfig,
+	): ReturnType<typeof attachSocketAdapter> {
+		const wss = new WebSocketServer({ server: this.httpServer })
+		return adapterFn(wss, config)
+	}
+
+	listen(port: number, hostname?: string): void {
+		const host = hostname ?? '0.0.0.0'
+		this.httpServer.listen(port, host, () => {
+			if (this.config.debug) {
+				console.info(`HTTP Server running at http://localhost:${port}`)
+				console.info(`WebSocket server running on ws://localhost:${port}`)
+			}
+		})
+	}
+}

package/src/local-server/types.ts

@@ -0,0 +1,35 @@
+import type { Context } from 'aws-lambda'
+import type {
+	APIGatewayProxyEventV2,
+	APIGatewayProxyStructuredResultV2,
+	ALBEvent,
+	ALBResult,
+} from 'aws-lambda'
+
+// --- Handler types ---
+
+export type ApiGatewayHandler = (
+	event: APIGatewayProxyEventV2,
+	context: Context,
+) => Promise<APIGatewayProxyStructuredResultV2>
+
+export type ALBHandler = (
+	event: ALBEvent,
+	context: Context,
+) => Promise<ALBResult>
+
+// --- Lambda options (discriminated) ---
+
+export interface LambdaOptionsApiGateway {
+	eventType?: 'api-gateway'
+}
+
+export interface LambdaOptionsALB {
+	eventType: 'alb'
+}
+
+// --- Server config ---
+
+export interface LocalServerConfig {
+	debug?: boolean
+}