@donkeylabs/server 1.0.1 → 1.1.0

package/docs/api-client.md

@@ -141,17 +141,201 @@ const order = await api.orders.create({ items: [...] }, {
 
 ### Raw Routes
 
-For non-JSON endpoints:
+For full Request/Response control:
 
 ```ts
 // Server-side
-router.route("download").raw({
-  handle: async (req, ctx) => new Response(fileBuffer),
+router.route("proxy").raw({
+  handle: async (req, ctx) => fetch("https://api.example.com"),
 });
 
 // Client-side (returns raw Response)
-const response = await api.files.download();
+const response = await api.proxy();
+const data = await response.json();
+```
+
+### Stream Routes
+
+Validated input with binary/streaming Response:
+
+```ts
+// Server-side
+router.route("files.download").stream({
+  input: z.object({ fileId: z.string(), quality: z.enum(["low", "high"]) }),
+  handle: async (input, ctx) => {
+    const file = await ctx.plugins.storage.get(input.fileId);
+    return new Response(file.stream, {
+      headers: { "Content-Type": file.mimeType },
+    });
+  },
+});
+
+// Client-side (typed input, returns Response)
+const response = await api.files.download({ fileId: "abc", quality: "high" });
 const blob = await response.blob();
+
+// For video/audio streaming
+const videoUrl = URL.createObjectURL(await response.blob());
+```
+
+### SSE Routes
+
+Server-Sent Events with automatic channel subscription and **typed event handlers**:
+
+```ts
+// Server-side - define events schema for type-safe client
+router.route("notifications.subscribe").sse({
+  input: z.object({ userId: z.string() }),
+  events: {
+    notification: z.object({ message: z.string(), id: z.string() }),
+    announcement: z.object({ title: z.string(), urgent: z.boolean() }),
+  },
+  handle: (input, ctx) => [`user:${input.userId}`, "global"],
+});
+
+// Client-side (returns typed SSEConnection)
+const connection = api.notifications.subscribe({ userId: "123" });
+
+// Type-safe event handlers - data is fully typed!
+const unsubNotif = connection.on("notification", (data) => {
+  // data: { message: string; id: string }
+  console.log("New notification:", data.message);
+});
+
+const unsubAnnounce = connection.on("announcement", (data) => {
+  // data: { title: string; urgent: boolean }
+  if (data.urgent) showAlert(data.title);
+});
+
+// Unsubscribe from specific handlers
+unsubNotif();
+
+// Handle connection events
+connection.onError((e) => console.error("Connection lost"));
+connection.onOpen(() => console.log("Connected"));
+
+// Check connection state
+console.log(connection.connected); // boolean
+console.log(connection.readyState); // EventSource.OPEN, CONNECTING, CLOSED
+
+// Close entire connection
+connection.close();
+```
+
+**Svelte 5 example:**
+```svelte
+<script lang="ts">
+  import { createApi } from '$lib/api';
+  import type { SSEConnection } from '@donkeylabs/adapter-sveltekit/client';
+
+  const api = createApi();
+  let messages = $state<{ message: string; id: string }[]>([]);
+  let connection: SSEConnection | null = null;
+
+  function connect() {
+    connection = api.notifications.subscribe({ userId: "123" });
+
+    // Typed event handler - no JSON.parse needed!
+    connection.on("notification", (data) => {
+      messages = [...messages, data]; // data is already typed
+    });
+  }
+
+  // Cleanup on unmount
+  $effect(() => () => connection?.close());
+</script>
+
+<button onclick={connect}>Connect</button>
+{#each messages as msg}<p>{msg.message}</p>{/each}
+```
+
+### FormData Routes
+
+File uploads with validated fields:
+
+```ts
+// Server-side
+router.route("files.upload").formData({
+  input: z.object({ folder: z.string(), tags: z.array(z.string()).optional() }),
+  output: z.object({ ids: z.array(z.string()), count: z.number() }),
+  files: { maxSize: 10 * 1024 * 1024, accept: ["image/*", "application/pdf"] },
+  handle: async ({ fields, files }, ctx) => {
+    const ids = await Promise.all(files.map(f => saveFile(f, fields.folder)));
+    return { ids, count: files.length };
+  },
+});
+
+// Client-side (fields + files array)
+const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
+const files = Array.from(fileInput.files || []);
+
+const result = await api.files.upload(
+  { folder: "photos", tags: ["vacation", "2024"] },
+  files
+);
+console.log(`Uploaded ${result.count} files:`, result.ids);
+```
+
+**Svelte 5 example:**
+```svelte
+<script lang="ts">
+  import { createApi } from '$lib/api';
+
+  const api = createApi();
+  let uploading = $state(false);
+  let result = $state<{ ids: string[]; count: number } | null>(null);
+
+  async function handleUpload(e: Event) {
+    const input = e.target as HTMLInputElement;
+    const files = Array.from(input.files || []);
+    if (!files.length) return;
+
+    uploading = true;
+    try {
+      result = await api.files.upload({ folder: "uploads" }, files);
+    } finally {
+      uploading = false;
+    }
+  }
+</script>
+
+<input type="file" multiple onchange={handleUpload} disabled={uploading} />
+{#if result}<p>Uploaded {result.count} files</p>{/if}
+```
+
+### HTML Routes
+
+HTML responses for htmx and server components:
+
+```ts
+// Server-side
+router.route("components.userCard").html({
+  input: z.object({ userId: z.string() }),
+  handle: async (input, ctx) => {
+    const user = await ctx.plugins.users.get(input.userId);
+    return `<div class="card">${user.name}</div>`;
+  },
+});
+
+// Client-side (returns HTML string)
+const html = await api.components.userCard({ userId: "123" });
+document.getElementById("container")!.innerHTML = html;
+```
+
+**htmx usage (no client needed):**
+```html
+<!-- htmx calls the route directly -->
+<div hx-get="/api/components.userCard?userId=123"
+     hx-trigger="load"
+     hx-swap="innerHTML">
+  Loading...
+</div>
+
+<!-- With click trigger -->
+<button hx-get="/api/components.userCard?userId=456"
+        hx-target="#card-container">
+  Load User
+</button>
 ```
 
 ---

package/docs/handlers.md

@@ -23,6 +23,15 @@ export const MyHandler = createHandler<MyFn>(async (req, def, handle, ctx) => {
 
 ## Built-in Handlers
 
+| Handler | Input | Output | HTTP Methods | Use Case |
+|---------|-------|--------|--------------|----------|
+| `typed` | Zod-validated JSON | Zod-validated JSON | POST | Standard API endpoints |
+| `raw` | Full Request | Full Response | Any | Proxies, WebSockets, custom protocols |
+| `stream` | Zod-validated (query/JSON) | Response (binary/stream) | GET, POST | File downloads, video/image serving |
+| `sse` | Zod-validated (query/JSON) | SSE connection | GET, POST | Real-time notifications |
+| `formData` | Zod-validated fields + files | Zod-validated JSON | POST | File uploads |
+| `html` | Zod-validated (query/JSON) | HTML string | GET, POST | htmx, server components |
+
 ### TypedHandler (Default)
 
 JSON-RPC style handler with automatic validation:
@@ -59,29 +68,347 @@ router.route("greet").typed({
 Full control over Request and Response:
 
 ```ts
-router.route("upload").raw({
+router.route("proxy").raw({
   handle: async (req, ctx) => {
-    if (req.method !== "POST") {
-      return new Response("Method Not Allowed", { status: 405 });
-    }
+    // Full access to request
+    const response = await fetch("https://api.example.com" + new URL(req.url).pathname, {
+      method: req.method,
+      headers: req.headers,
+      body: req.body,
+    });
+    return response;
+  },
+});
+```
 
-    const formData = await req.formData();
-    const file = formData.get("file") as File;
+**Use cases:**
+- Proxying requests
+- WebSocket upgrades
+- Custom protocols
+- Non-standard HTTP methods
 
-    // Process file...
+---
 
-    return Response.json({ success: true });
+### StreamHandler
+
+Validated input with custom Response output. Best for binary data and streaming:
+
+```ts
+router.route("files.download").stream({
+  input: z.object({
+    fileId: z.string(),
+    format: z.enum(["mp4", "webm"])
+  }),
+  handle: async (input, ctx) => {
+    const file = await ctx.plugins.storage.getFile(input.fileId);
+
+    return new Response(file.stream, {
+      headers: {
+        "Content-Type": `video/${input.format}`,
+        "Content-Disposition": `attachment; filename="${input.fileId}.${input.format}"`,
+      },
+    });
   },
 });
 ```
 
+**Behavior:**
+- Accepts GET (query params) or POST (JSON body)
+- Parses and validates input with Zod
+- Returns Response directly (no output validation)
+
 **Use cases:**
-- File uploads/downloads
-- Streaming responses
-- Server-Sent Events
-- Custom content types
-- WebSocket upgrades
-- Non-JSON APIs
+- File downloads with parameters
+- Video/audio streaming
+- Binary data with metadata
+- Custom content-types
+- Image serving (`<img src="...">`)
+- Video embedding (`<video src="...">`)
+
+**Generated Client:**
+
+The generated client provides three methods for stream routes:
+
+```ts
+// 1. fetch() - POST request with JSON body (programmatic use)
+const response = await api.files.download.fetch({ fileId: "abc", format: "mp4" });
+const blob = await response.blob();
+
+// 2. url() - GET URL for browser src attributes
+const url = api.files.download.url({ fileId: "abc", format: "mp4" });
+// Returns: "/api.files.download?fileId=abc&format=mp4"
+
+// 3. get() - GET request with query params
+const response = await api.files.download.get({ fileId: "abc", format: "mp4" });
+```
+
+**HTML/Svelte Usage:**
+
+```svelte
+<script>
+  import { createApi } from '$lib/api';
+  const api = createApi();
+</script>
+
+<!-- Video element with stream URL -->
+<video src={api.videos.stream.url({ id: "video-123" })} controls />
+
+<!-- Image with dynamic src -->
+<img src={api.images.thumbnail.url({ id: "img-456", size: "medium" })} />
+
+<!-- Download link -->
+<a href={api.files.download.url({ fileId: "doc-789" })} download>
+  Download File
+</a>
+```
+
+---
+
+### SSEHandler
+
+Server-Sent Events with validated input, automatic channel subscription, and **typed events**:
+
+```ts
+router.route("notifications.subscribe").sse({
+  input: z.object({
+    userId: z.string(),
+    channels: z.array(z.string()).optional(),
+  }),
+  // Define event schemas for type-safe generated clients
+  events: {
+    notification: z.object({ message: z.string(), id: z.string() }),
+    announcement: z.object({ title: z.string(), urgent: z.boolean() }),
+  },
+  handle: (input, ctx) => {
+    // Return channel names to subscribe to
+    const channels = [`user:${input.userId}`, "global"];
+    if (input.channels) {
+      channels.push(...input.channels);
+    }
+    return channels;
+  },
+});
+```
+
+**Behavior:**
+- Accepts GET (query params) or POST (JSON body)
+- Validates input with Zod schema
+- Creates SSE connection via `ctx.core.sse`
+- Subscribes client to returned channels
+- Supports `Last-Event-ID` header for reconnection
+- `events` schema enables typed event handlers in generated client
+
+**Broadcasting Events (Server-side):**
+```ts
+// In your service or handler
+ctx.core.sse.broadcast("user:123", "notification", {
+  message: "New message received",
+  id: "notif-123"
+});
+
+// Broadcast to all connected clients
+ctx.core.sse.broadcastAll("announcement", {
+  title: "Server maintenance in 5 minutes",
+  urgent: true
+});
+```
+
+**Generated Client (Typed):**
+```ts
+// Connect to SSE endpoint - returns typed SSEConnection
+const connection = api.notifications.subscribe({ userId: "123" });
+
+// Type-safe event handlers - data is fully typed, no JSON.parse needed!
+const unsubNotif = connection.on("notification", (data) => {
+  // data: { message: string; id: string }
+  console.log("Notification:", data.message);
+});
+
+const unsubAnnounce = connection.on("announcement", (data) => {
+  // data: { title: string; urgent: boolean }
+  if (data.urgent) showAlert(data.title);
+});
+
+// Unsubscribe from specific handlers
+unsubNotif();
+
+// Handle connection events
+connection.onError((e) => console.error("SSE connection error"));
+connection.onOpen(() => console.log("Connected"));
+
+// Check connection state
+connection.connected;   // boolean
+connection.readyState;  // 0=CONNECTING, 1=OPEN, 2=CLOSED
+
+// Close entire connection
+connection.close();
+```
+
+**Svelte 5 Example:**
+```svelte
+<script lang="ts">
+  import { createApi } from '$lib/api';
+  import type { SSEConnection } from '@donkeylabs/adapter-sveltekit/client';
+
+  const api = createApi();
+  let notifications = $state<{ message: string; id: string }[]>([]);
+  let connection: SSEConnection | null = null;
+
+  function connect(userId: string) {
+    connection = api.notifications.subscribe({ userId });
+
+    // Typed event handler - no JSON.parse needed!
+    connection.on("notification", (data) => {
+      notifications = [...notifications, data]; // data is already typed
+    });
+  }
+
+  function disconnect() {
+    connection?.close();
+    connection = null;
+  }
+
+  // Cleanup on unmount
+  $effect(() => {
+    return () => connection?.close();
+  });
+</script>
+```
+
+---
+
+### FormDataHandler
+
+File uploads with validated form fields and file constraints:
+
+```ts
+router.route("files.upload").formData({
+  input: z.object({
+    folder: z.string(),
+    description: z.string().optional(),
+  }),
+  output: z.object({
+    ids: z.array(z.string()),
+    count: z.number(),
+  }),
+  files: {
+    maxSize: 10 * 1024 * 1024,  // 10MB
+    accept: ["image/*", "application/pdf"],
+  },
+  handle: async ({ fields, files }, ctx) => {
+    const ids: string[] = [];
+
+    for (const file of files) {
+      const id = await ctx.plugins.storage.save(file, fields.folder);
+      ids.push(id);
+    }
+
+    return { ids, count: files.length };
+  },
+});
+```
+
+**Behavior:**
+- Accepts POST requests only
+- Requires `multipart/form-data` content type
+- Separates form fields from files
+- Validates fields with Zod schema
+- Validates output with Zod schema (if provided)
+- Enforces file constraints before calling handler
+
+**File Constraints:**
+```ts
+files: {
+  maxSize?: number;      // Max file size in bytes
+  accept?: string[];     // MIME types (supports wildcards like "image/*")
+}
+```
+
+**Error Responses:**
+
+| Status | Condition |
+|--------|-----------|
+| 405 | Non-POST request |
+| 400 | Not multipart/form-data |
+| 400 | Field validation failed |
+| 400 | File exceeds maxSize |
+| 400 | File type not in accept list |
+
+**Generated Client:**
+```ts
+const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
+const files = Array.from(fileInput.files || []);
+
+const result = await api.files.upload(
+  { folder: "uploads", description: "My photos" },
+  files
+);
+console.log(`Uploaded ${result.count} files:`, result.ids);
+```
+
+---
+
+### HTMLHandler
+
+Returns HTML responses. Perfect for htmx, partial renders, and server components:
+
+```ts
+router.route("components.userCard").html({
+  input: z.object({ userId: z.string() }),
+  handle: async (input, ctx) => {
+    const user = await ctx.plugins.users.get(input.userId);
+
+    return `
+      <div class="card" id="user-${user.id}">
+        <img src="${user.avatar}" alt="${user.name}" />
+        <h3>${user.name}</h3>
+        <p>${user.bio}</p>
+      </div>
+    `;
+  },
+});
+```
+
+**Behavior:**
+- Accepts GET (query params) or POST (JSON/form-urlencoded)
+- Validates input with Zod schema
+- Returns `text/html` content type
+- Can return string (wrapped in Response) or custom Response
+- Returns HTML-formatted errors
+
+**Use Cases:**
+- htmx partials
+- Server-side rendered components
+- Email templates
+- PDF generation (return Response with different content-type)
+
+**Returning Custom Response:**
+```ts
+router.route("pages.redirect").html({
+  input: z.object({ to: z.string() }),
+  handle: (input) => {
+    return new Response(null, {
+      status: 302,
+      headers: { Location: input.to },
+    });
+  },
+});
+```
+
+**Generated Client:**
+```ts
+const html = await api.components.userCard({ userId: "123" });
+document.getElementById("container").innerHTML = html;
+```
+
+**htmx Example:**
+```html
+<div hx-get="/api/components.userCard?userId=123"
+     hx-trigger="load"
+     hx-swap="innerHTML">
+  Loading...
+</div>
+```
 
 ---
 

package/docs/router.md

@@ -44,8 +44,12 @@ After calling `router.route("name")`, you get a RouteBuilder with handler method
 
 | Method | Description |
 |--------|-------------|
-| `.typed(config)` | JSON-RPC style handler (default) |
+| `.typed(config)` | JSON-RPC style handler with Zod validation |
 | `.raw(config)` | Full Request/Response control |
+| `.stream(config)` | Validated input, Response output (binary/streaming) |
+| `.sse(config)` | Server-Sent Events with channel subscription |
+| `.formData(config)` | File uploads with validated fields |
+| `.html(config)` | HTML responses for htmx/components |
 | `.<custom>(config)` | Custom handlers from plugins |
 
 ### MiddlewareBuilder Methods
@@ -119,22 +123,132 @@ router.route("greet").typed({
 Full control over Request/Response:
 
 ```ts
-router.route("download").raw({
+router.route("proxy").raw({
   handle: async (req, ctx) => {
-    const file = await Bun.file("data.csv").text();
-    return new Response(file, {
-      headers: { "Content-Type": "text/csv" },
+    return fetch("https://api.example.com", {
+      method: req.method,
+      headers: req.headers,
+      body: req.body,
     });
   },
 });
 ```
 
 **Use cases:**
-- File uploads/downloads
-- Streaming responses
-- SSE endpoints
-- Custom content types
+- Proxying requests
 - WebSocket upgrades
+- Custom protocols
+
+### Stream Handler
+
+Validated input with binary/streaming Response:
+
+```ts
+router.route("files.download").stream({
+  input: z.object({ fileId: z.string() }),
+  handle: async (input, ctx) => {
+    const file = await ctx.plugins.storage.get(input.fileId);
+    return new Response(file.stream, {
+      headers: { "Content-Type": file.mimeType },
+    });
+  },
+});
+```
+
+**Use cases:**
+- File downloads with parameters
+- Video/audio streaming
+- Binary data with metadata
+
+### SSE Handler
+
+Server-Sent Events with automatic channel subscription and typed events:
+
+```ts
+router.route("events.subscribe").sse({
+  input: z.object({ userId: z.string() }),
+  // Optional: Define event schemas for type-safe generated clients
+  events: {
+    notification: z.object({ message: z.string(), id: z.string() }),
+    announcement: z.object({ title: z.string(), urgent: z.boolean() }),
+  },
+  handle: (input, ctx) => {
+    // Return channels to subscribe to
+    return [`user:${input.userId}`, "global"];
+  },
+});
+```
+
+**Server-side broadcasting:**
+```ts
+ctx.core.sse.broadcast("user:123", "notification", { message: "Hello!", id: "1" });
+```
+
+**Generated client usage:**
+```ts
+const connection = api.events.subscribe({ userId: "123" });
+
+// Typed event handlers - no JSON.parse needed
+connection.on("notification", (data) => {
+  // data: { message: string; id: string }
+  console.log(data.message);
+});
+
+// Returns unsubscribe function
+const unsub = connection.on("announcement", (data) => {
+  if (data.urgent) showAlert(data.title);
+});
+unsub(); // Unsubscribe from this handler
+
+connection.close(); // Close the entire connection
+```
+
+**Use cases:**
+- Real-time notifications
+- Live updates
+- Event streaming
+
+### FormData Handler
+
+File uploads with validated fields:
+
+```ts
+router.route("files.upload").formData({
+  input: z.object({ folder: z.string() }),
+  output: z.object({ ids: z.array(z.string()) }),
+  files: { maxSize: 10 * 1024 * 1024, accept: ["image/*"] },
+  handle: async ({ fields, files }, ctx) => {
+    const ids = await Promise.all(
+      files.map(f => ctx.plugins.storage.save(f, fields.folder))
+    );
+    return { ids };
+  },
+});
+```
+
+**Use cases:**
+- File uploads
+- Form submissions with attachments
+- Multi-file uploads
+
+### HTML Handler
+
+HTML responses for htmx and server components:
+
+```ts
+router.route("components.card").html({
+  input: z.object({ userId: z.string() }),
+  handle: async (input, ctx) => {
+    const user = await ctx.plugins.users.get(input.userId);
+    return `<div class="card">${user.name}</div>`;
+  },
+});
+```
+
+**Use cases:**
+- htmx partials
+- Server-rendered components
+- Email templates
 
 ### Custom Handlers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",

package/src/generator/index.ts

@@ -17,6 +17,8 @@ export interface RouteInfo {
   handler: "typed" | "raw" | string;
   inputSource?: string;
   outputSource?: string;
+  /** SSE event schemas (for sse handler) */
+  eventsSource?: Record<string, string>;
 }
 
 export interface EventInfo {

package/src/handlers.ts

@@ -79,8 +79,331 @@ export const RawHandler: RawHandler = {
   __signature: undefined as unknown as RawFn
 }
 
+// ==========================================
+// 3. Stream Handler (Validated input, custom Response output)
+// ==========================================
+/**
+ * Stream handler function signature.
+ * Like typed, but returns a Response instead of JSON-serializable data.
+ * Use this for streaming, binary data, custom content-types, etc.
+ *
+ * Accepts both GET (query params) and POST (JSON body) for flexibility:
+ * - GET /files.download?fileId=123 (for browser links, video src, etc.)
+ * - POST /files.download {"fileId": "123"} (for programmatic requests)
+ */
+export type StreamFn<I = any> = (input: I, ctx: ServerContext) => Promise<Response> | Response;
+export type StreamHandler = HandlerRuntime<StreamFn>;
+
+export const StreamHandler: StreamHandler = {
+  async execute(req, def, handle, ctx) {
+    // Stream routes accept GET (for browser, <video src>, etc.) and POST
+    if (req.method !== "GET" && req.method !== "POST") {
+      return new Response("Method Not Allowed", { status: 405 });
+    }
+
+    try {
+      // Parse input from query params (GET) or body (POST)
+      let body: any = {};
+      if (req.method === "POST") {
+        try {
+          body = await req.json();
+        } catch {
+          return Response.json({ error: "Invalid JSON" }, { status: 400 });
+        }
+      } else {
+        // Parse query params for GET requests
+        const url = new URL(req.url);
+        for (const [key, value] of url.searchParams) {
+          // Try to parse JSON values, otherwise use string
+          try {
+            body[key] = JSON.parse(value);
+          } catch {
+            body[key] = value;
+          }
+        }
+      }
+
+      // Validate input with Zod (like typed)
+      const input = def.input ? def.input.parse(body) : body;
+      // But return Response directly (like raw) - no output validation
+      return await handle(input, ctx);
+    } catch (e: any) {
+      console.error(e);
+      if (e instanceof z.ZodError) {
+        return Response.json({ error: "Validation Failed", details: e.issues }, { status: 400 });
+      }
+      return Response.json({ error: e.message || "Internal Error" }, { status: e.status || 500 });
+    }
+  },
+  __signature: undefined as unknown as StreamFn
+}
+
+// ==========================================
+// 4. SSE Handler (Server-Sent Events)
+// ==========================================
+/**
+ * SSE handler function signature.
+ * Returns channels to subscribe to based on validated input.
+ * The handler sets up the SSE connection and subscribes to channels.
+ */
+export type SSEFn<I = any> = (input: I, ctx: ServerContext) => string[] | Promise<string[]>;
+export type SSEHandler = HandlerRuntime<SSEFn>;
+
+export const SSEHandler: SSEHandler = {
+  async execute(req, def, handle, ctx) {
+    // SSE typically uses GET, but we also support POST for input
+    if (req.method !== "GET" && req.method !== "POST") {
+      return new Response("Method Not Allowed", { status: 405 });
+    }
+
+    try {
+      // Parse input from query params (GET) or body (POST)
+      let body: any = {};
+      if (req.method === "POST") {
+        try {
+          body = await req.json();
+        } catch {
+          return Response.json({ error: "Invalid JSON" }, { status: 400 });
+        }
+      } else {
+        // Parse query params for GET requests
+        const url = new URL(req.url);
+        for (const [key, value] of url.searchParams) {
+          // Try to parse JSON values, otherwise use string
+          try {
+            body[key] = JSON.parse(value);
+          } catch {
+            body[key] = value;
+          }
+        }
+      }
+
+      // Validate input
+      const input = def.input ? def.input.parse(body) : body;
+
+      // Get channels from handler
+      const channels = await handle(input, ctx);
+
+      // Create SSE client and response
+      const { client, response } = ctx.core.sse.addClient({
+        lastEventId: req.headers.get("Last-Event-ID") || undefined,
+      });
+
+      // Subscribe to channels
+      for (const channel of channels) {
+        ctx.core.sse.subscribe(client.id, channel);
+      }
+
+      return response;
+    } catch (e: any) {
+      console.error(e);
+      if (e instanceof z.ZodError) {
+        return Response.json({ error: "Validation Failed", details: e.issues }, { status: 400 });
+      }
+      return Response.json({ error: e.message || "Internal Error" }, { status: e.status || 500 });
+    }
+  },
+  __signature: undefined as unknown as SSEFn
+};
+
+// ==========================================
+// 5. FormData Handler (File Uploads / Multipart)
+// ==========================================
+/**
+ * Parsed form data passed to handler.
+ */
+export interface ParsedFormData<F = any> {
+  fields: F;
+  files: File[];
+}
+
+/**
+ * FormData handler function signature.
+ * Receives validated fields and files array.
+ */
+export type FormDataFn<F = any, O = any> = (
+  data: ParsedFormData<F>,
+  ctx: ServerContext
+) => Promise<O> | O;
+export type FormDataHandler = HandlerRuntime<FormDataFn>;
+
+export const FormDataHandler: FormDataHandler = {
+  async execute(req, def, handle, ctx) {
+    if (req.method !== "POST") {
+      return new Response("Method Not Allowed", { status: 405 });
+    }
+
+    const contentType = req.headers.get("Content-Type") || "";
+    if (!contentType.includes("multipart/form-data")) {
+      return Response.json(
+        { error: "Content-Type must be multipart/form-data" },
+        { status: 400 }
+      );
+    }
+
+    try {
+      const formData = await req.formData();
+
+      // Separate fields and files
+      const fields: Record<string, any> = {};
+      const files: File[] = [];
+
+      for (const [key, value] of formData.entries()) {
+        // Check if value is a File (not a string)
+        if (typeof value !== "string") {
+          const file = value as File;
+          // Check file constraints if defined
+          if (def.fileConstraints) {
+            const { maxSize, accept } = def.fileConstraints;
+
+            if (maxSize && file.size > maxSize) {
+              return Response.json(
+                { error: `File "${file.name}" exceeds max size of ${maxSize} bytes` },
+                { status: 400 }
+              );
+            }
+
+            if (accept && accept.length > 0) {
+              const isAccepted = accept.some((pattern: string) => {
+                if (pattern.endsWith("/*")) {
+                  const prefix = pattern.slice(0, -1);
+                  return file.type.startsWith(prefix);
+                }
+                return file.type === pattern;
+              });
+
+              if (!isAccepted) {
+                return Response.json(
+                  { error: `File "${file.name}" has invalid type "${file.type}"` },
+                  { status: 400 }
+                );
+              }
+            }
+          }
+          files.push(file);
+        } else {
+          // Try to parse JSON values
+          try {
+            fields[key] = JSON.parse(value);
+          } catch {
+            fields[key] = value;
+          }
+        }
+      }
+
+      // Validate fields with Zod schema
+      const validatedFields = def.input ? def.input.parse(fields) : fields;
+
+      // Call handler
+      const result = await handle({ fields: validatedFields, files }, ctx);
+
+      // Validate and return output
+      const output = def.output ? def.output.parse(result) : result;
+      return Response.json(output);
+    } catch (e: any) {
+      console.error(e);
+      if (e instanceof z.ZodError) {
+        return Response.json({ error: "Validation Failed", details: e.issues }, { status: 400 });
+      }
+      return Response.json({ error: e.message || "Internal Error" }, { status: e.status || 500 });
+    }
+  },
+  __signature: undefined as unknown as FormDataFn
+};
+
+// ==========================================
+// 6. HTML Handler (HTML Responses)
+// ==========================================
+/**
+ * HTML handler function signature.
+ * Returns HTML string or Response.
+ */
+export type HTMLFn<I = any> = (input: I, ctx: ServerContext) => string | Response | Promise<string | Response>;
+export type HTMLHandler = HandlerRuntime<HTMLFn>;
+
+export const HTMLHandler: HTMLHandler = {
+  async execute(req, def, handle, ctx) {
+    // HTML routes typically use GET, but support POST for form submissions
+    if (req.method !== "GET" && req.method !== "POST") {
+      return new Response("Method Not Allowed", { status: 405 });
+    }
+
+    try {
+      // Parse input from query params (GET) or body (POST)
+      let body: any = {};
+      if (req.method === "POST") {
+        const contentType = req.headers.get("Content-Type") || "";
+        if (contentType.includes("application/json")) {
+          try {
+            body = await req.json();
+          } catch {
+            return Response.json({ error: "Invalid JSON" }, { status: 400 });
+          }
+        } else if (contentType.includes("application/x-www-form-urlencoded")) {
+          const formData = await req.formData();
+          for (const [key, value] of formData.entries()) {
+            if (typeof value === "string") {
+              try {
+                body[key] = JSON.parse(value);
+              } catch {
+                body[key] = value;
+              }
+            }
+          }
+        }
+      } else {
+        // Parse query params for GET requests
+        const url = new URL(req.url);
+        for (const [key, value] of url.searchParams) {
+          try {
+            body[key] = JSON.parse(value);
+          } catch {
+            body[key] = value;
+          }
+        }
+      }
+
+      // Validate input
+      const input = def.input ? def.input.parse(body) : body;
+
+      // Call handler
+      const result = await handle(input, ctx);
+
+      // If handler returns Response, return it directly
+      if (result instanceof Response) {
+        return result;
+      }
+
+      // Return HTML string with proper content-type
+      return new Response(result, {
+        headers: {
+          "Content-Type": "text/html; charset=utf-8",
+        },
+      });
+    } catch (e: any) {
+      console.error(e);
+      if (e instanceof z.ZodError) {
+        // Return HTML error for HTML handler
+        return new Response(
+          `<html><body><h1>Validation Error</h1><pre>${JSON.stringify(e.issues, null, 2)}</pre></body></html>`,
+          { status: 400, headers: { "Content-Type": "text/html; charset=utf-8" } }
+        );
+      }
+      return new Response(
+        `<html><body><h1>Error</h1><p>${e.message || "Internal Error"}</p></body></html>`,
+        { status: e.status || 500, headers: { "Content-Type": "text/html; charset=utf-8" } }
+      );
+    }
+  },
+  __signature: undefined as unknown as HTMLFn
+};
+
 export const Handlers = {
     typed: TypedHandler,
-    raw: RawHandler
+    raw: RawHandler,
+    stream: StreamHandler,
+    sse: SSEHandler,
+    formData: FormDataHandler,
+    html: HTMLHandler
 };
 

package/src/router.ts

@@ -8,6 +8,15 @@ export type ServerContext = GlobalContext;
 /** Base interface for middleware builder - extended by generated types */
 export interface IMiddlewareBuilder<TRouter> {}
 
+/** Parsed form data passed to formData handler */
+export interface ParsedFormData<F = any> {
+  fields: F;
+  files: File[];
+}
+
+/** Schema definitions for SSE events */
+export type SSEEventSchemas = Record<string, z.ZodType<any>>;
+
 export interface HandlerRegistry extends PluginHandlerRegistry {
     typed: {
         execute(req: Request, def: any, userHandle: Function, ctx: ServerContext): Promise<Response>;
@@ -17,17 +26,38 @@ export interface HandlerRegistry extends PluginHandlerRegistry {
         execute(req: Request, def: any, userHandle: Function, ctx: ServerContext): Promise<Response>;
         readonly __signature: (req: Request, ctx: ServerContext) => Promise<Response> | Response;
     };
+    stream: {
+        execute(req: Request, def: any, userHandle: Function, ctx: ServerContext): Promise<Response>;
+        readonly __signature: (input: any, ctx: ServerContext) => Promise<Response> | Response;
+    };
+    sse: {
+        execute(req: Request, def: any, userHandle: Function, ctx: ServerContext): Promise<Response>;
+        readonly __signature: (input: any, ctx: ServerContext) => string[] | Promise<string[]>;
+    };
+    formData: {
+        execute(req: Request, def: any, userHandle: Function, ctx: ServerContext): Promise<Response>;
+        readonly __signature: (data: ParsedFormData, ctx: ServerContext) => Promise<any> | any;
+    };
+    html: {
+        execute(req: Request, def: any, userHandle: Function, ctx: ServerContext): Promise<Response>;
+        readonly __signature: (input: any, ctx: ServerContext) => string | Response | Promise<string | Response>;
+    };
 }
 
 export type RouteDefinition<
     T extends keyof HandlerRegistry = "typed",
     I = any,
-    O = any
+    O = any,
+    E extends SSEEventSchemas = SSEEventSchemas
 > = {
   name: string;
   handler: T;
   input?: z.ZodType<I>;
   output?: z.ZodType<O>;
+  /** SSE event schemas (for sse handler only) */
+  events?: E;
+  /** File constraints for formData handler */
+  fileConstraints?: FileConstraints;
   middleware?: MiddlewareDefinition[];
   handle: T extends "typed"
     ? (input: I, ctx: ServerContext) => Promise<O> | O
@@ -61,9 +91,113 @@ export interface RawRouteConfig {
   handle: (req: Request, ctx: ServerContext) => Promise<Response> | Response;
 }
 
+export interface StreamRouteConfig<I = any> {
+  input?: z.ZodType<I>;
+  handle: (input: I, ctx: ServerContext) => Promise<Response> | Response;
+}
+
+/** File upload constraints for formData handler */
+export interface FileConstraints {
+  /** Max file size in bytes */
+  maxSize?: number;
+  /** Accepted MIME types (e.g., "image/*", "application/pdf") */
+  accept?: string[];
+}
+
+export interface SSERouteConfig<I = any, E extends SSEEventSchemas = SSEEventSchemas> {
+  input?: z.ZodType<I>;
+  /** Event schemas for type-safe client generation */
+  events?: E;
+  /** Return channel names to subscribe to */
+  handle: (input: I, ctx: ServerContext) => string[] | Promise<string[]>;
+}
+
+export interface FormDataRouteConfig<F = any, O = any> {
+  /** Schema for form fields (non-file data) */
+  input?: z.ZodType<F>;
+  /** Schema for output validation */
+  output?: z.ZodType<O>;
+  /** File upload constraints */
+  files?: FileConstraints;
+  handle: (data: ParsedFormData<F>, ctx: ServerContext) => Promise<O> | O;
+}
+
+export interface HTMLRouteConfig<I = any> {
+  input?: z.ZodType<I>;
+  handle: (input: I, ctx: ServerContext) => string | Response | Promise<string | Response>;
+}
+
 export interface IRouteBuilderBase<TRouter> {
   typed<I, O>(config: TypedRouteConfig<I, O>): TRouter;
   raw(config: RawRouteConfig): TRouter;
+  /**
+   * Stream handler - validated input, custom Response output.
+   * Use for streaming, binary data, files, custom content-types, etc.
+   *
+   * @example
+   * ```ts
+   * api.route("files.download").stream({
+   *   input: z.object({ fileId: z.string() }),
+   *   handle: async (input, ctx) => {
+   *     const file = await getFile(input.fileId);
+   *     return new Response(file.stream, {
+   *       headers: { "Content-Type": file.mimeType }
+   *     });
+   *   }
+   * });
+   * ```
+   */
+  stream<I>(config: StreamRouteConfig<I>): TRouter;
+  /**
+   * SSE handler - Server-Sent Events with validated input and typed events.
+   * Returns channel names to subscribe the client to.
+   *
+   * @example
+   * ```ts
+   * api.route("notifications.subscribe").sse({
+   *   input: z.object({ userId: z.string() }),
+   *   events: {
+   *     notification: z.object({ message: z.string(), id: z.string() }),
+   *     announcement: z.object({ title: z.string(), urgent: z.boolean() }),
+   *   },
+   *   handle: (input, ctx) => [`user:${input.userId}`, "global"]
+   * });
+   * ```
+   */
+  sse<I, E extends SSEEventSchemas>(config: SSERouteConfig<I, E>): TRouter;
+  /**
+   * FormData handler - file uploads with validated fields.
+   * Receives parsed form fields and files array.
+   *
+   * @example
+   * ```ts
+   * api.route("files.upload").formData({
+   *   input: z.object({ folder: z.string() }),
+   *   files: { maxSize: 10 * 1024 * 1024, accept: ["image/*"] },
+   *   handle: async ({ fields, files }, ctx) => {
+   *     const uploaded = await saveFiles(files, fields.folder);
+   *     return { count: uploaded.length };
+   *   }
+   * });
+   * ```
+   */
+  formData<F, O>(config: FormDataRouteConfig<F, O>): TRouter;
+  /**
+   * HTML handler - returns HTML responses.
+   * Perfect for htmx, partial renders, or server components.
+   *
+   * @example
+   * ```ts
+   * api.route("components.userCard").html({
+   *   input: z.object({ userId: z.string() }),
+   *   handle: async (input, ctx) => {
+   *     const user = await ctx.plugins.users.get(input.userId);
+   *     return `<div class="card">${user.name}</div>`;
+   *   }
+   * });
+   * ```
+   */
+  html<I>(config: HTMLRouteConfig<I>): TRouter;
 }
 
 export interface IRouteBuilder<TRouter> extends IRouteBuilderBase<TRouter> {}
@@ -88,6 +222,27 @@ export class RouteBuilder<TRouter extends Router> implements IRouteBuilderBase<T
     return this.router.addRoute(this.name, "raw", config, this._middleware);
   }
 
+  stream<I>(config: StreamRouteConfig<I>): TRouter {
+    return this.router.addRoute(this.name, "stream", config, this._middleware);
+  }
+
+  sse<I, E extends SSEEventSchemas>(config: SSERouteConfig<I, E>): TRouter {
+    return this.router.addRoute(this.name, "sse", config, this._middleware);
+  }
+
+  formData<F, O>(config: FormDataRouteConfig<F, O>): TRouter {
+    // Map files constraints to fileConstraints for the handler
+    const routeConfig = {
+      ...config,
+      fileConstraints: config.files,
+    };
+    return this.router.addRoute(this.name, "formData", routeConfig, this._middleware);
+  }
+
+  html<I>(config: HTMLRouteConfig<I>): TRouter {
+    return this.router.addRoute(this.name, "html", config, this._middleware);
+  }
+
   addHandler(handler: string, config: any): TRouter {
     return this.router.addRoute(this.name, handler, config, this._middleware);
   }
@@ -174,15 +329,27 @@ export class Router implements IRouter {
     handler: string;
     inputType?: string;
     outputType?: string;
+    eventsType?: Record<string, string>;
   }> {
     // Dynamic import to avoid circular deps
     const { zodSchemaToTs } = require("./generator/zod-to-ts");
-    return this.getRoutes().map(route => ({
-      name: route.name,
-      handler: route.handler,
-      inputType: route.input ? zodSchemaToTs(route.input) : undefined,
-      outputType: route.output ? zodSchemaToTs(route.output) : undefined,
-    }));
+    return this.getRoutes().map(route => {
+      // Extract events schemas for SSE routes
+      let eventsType: Record<string, string> | undefined;
+      if (route.handler === "sse" && route.events) {
+        eventsType = {};
+        for (const [eventName, eventSchema] of Object.entries(route.events)) {
+          eventsType[eventName] = zodSchemaToTs(eventSchema);
+        }
+      }
+      return {
+        name: route.name,
+        handler: route.handler,
+        inputType: route.input ? zodSchemaToTs(route.input) : undefined,
+        outputType: route.output ? zodSchemaToTs(route.output) : undefined,
+        eventsType,
+      };
+    });
   }
 
   getPrefix(): string {

package/src/server.ts

@@ -604,7 +604,7 @@ ${factoryFunction}
 
     // Final handler
     const finalHandler = async () => {
-      const response = await handler.execute(req, route, route.handle, ctx);
+      const response = await handler.execute(req, route, route.handle as any, ctx);
       // Add CORS headers if provided
       if (Object.keys(corsHeaders).length > 0 && response instanceof Response) {
         const newHeaders = new Headers(response.headers);
@@ -820,7 +820,7 @@ ${factoryFunction}
 
             // Final handler execution
             const finalHandler = async () => {
-              return await handler.execute(req, route, route.handle, ctx);
+              return await handler.execute(req, route, route.handle as any, ctx);
             };
 
             // Execute middleware chain, then handler - with HttpError handling