@donkeylabs/server 1.1.7 → 1.1.9

package/package.json

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

package/src/client/base.ts

@@ -177,6 +177,23 @@ export interface SSEOptions {
   reconnectDelay?: number;
 }
 
+/**
+ * SSE subscription returned by route-specific SSE methods.
+ * Provides typed event handling for the route's defined events.
+ */
+export interface SSESubscription<TEvents extends Record<string, any>> {
+  /** Subscribe to a typed event. Returns unsubscribe function. */
+  on<E extends keyof TEvents>(event: E, handler: (data: TEvents[E]) => void): () => void;
+  /** Subscribe to an event once. Returns unsubscribe function. */
+  once<E extends keyof TEvents>(event: E, handler: (data: TEvents[E]) => void): () => void;
+  /** Remove all handlers for an event. */
+  off<E extends keyof TEvents>(event: E): void;
+  /** Close the SSE connection. */
+  close(): void;
+  /** Whether the connection is currently open. */
+  readonly connected: boolean;
+}
+
 // ============================================
 // Base Client Implementation
 // ============================================
@@ -268,10 +285,209 @@ export class ApiClientBase<TEvents extends Record<string, any> = Record<string,
     });
   }
 
+  /**
+   * Make a stream/html request with validated input, returns raw Response
+   */
+  protected async streamRequest<TInput>(
+    route: string,
+    input: TInput
+  ): Promise<Response> {
+    const fetchFn = this.options.fetch || fetch;
+
+    return fetchFn(`${this.baseUrl}/${route}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...this.options.headers,
+      },
+      credentials: this.options.credentials,
+      body: JSON.stringify(input),
+    });
+  }
+
+  /**
+   * Upload form data with files
+   */
+  protected async uploadFormData<TFields, TOutput>(
+    route: string,
+    fields: TFields,
+    files?: File[]
+  ): Promise<TOutput> {
+    const fetchFn = this.options.fetch || fetch;
+    const formData = new FormData();
+
+    // Add fields as JSON values
+    for (const [key, value] of Object.entries(fields as Record<string, any>)) {
+      formData.append(key, typeof value === "string" ? value : JSON.stringify(value));
+    }
+
+    // Add files
+    if (files) {
+      for (const file of files) {
+        formData.append("file", file);
+      }
+    }
+
+    const response = await fetchFn(`${this.baseUrl}/${route}`, {
+      method: "POST",
+      headers: {
+        ...this.options.headers,
+        // Don't set Content-Type - browser will set it with boundary
+      },
+      credentials: this.options.credentials,
+      body: formData,
+    });
+
+    if (!response.ok) {
+      const body = (await response.json().catch(() => ({}))) as Record<string, any>;
+      if (response.status === 400 && body.details?.issues) {
+        throw new ValidationError(body.details.issues);
+      }
+      throw new ApiError(response.status, body, body.message);
+    }
+
+    if (response.status === 204) {
+      return undefined as TOutput;
+    }
+
+    return response.json() as Promise<TOutput>;
+  }
+
   // ==========================================
   // SSE Connection Methods
   // ==========================================
 
+  /**
+   * Connect to a specific SSE route endpoint.
+   * Used by generated client methods for .sse() routes.
+   * @returns SSE subscription with typed event handlers
+   */
+  protected connectToSSERoute<TEvents extends Record<string, any>>(
+    route: string,
+    input: Record<string, any> = {},
+    options: Omit<SSEOptions, "endpoint" | "channels"> = {}
+  ): SSESubscription<TEvents> {
+    const url = new URL(`${this.baseUrl}/${route}`);
+
+    // Add input as query params
+    for (const [key, value] of Object.entries(input)) {
+      if (value !== undefined && value !== null) {
+        url.searchParams.set(key, typeof value === "string" ? value : JSON.stringify(value));
+      }
+    }
+
+    const eventSource = new EventSource(url.toString(), {
+      withCredentials: true,
+    });
+
+    const handlers = new Map<string, Set<(data: any) => void>>();
+    let onConnectCallback: (() => void) | undefined = options.onConnect;
+    let onDisconnectCallback: (() => void) | undefined = options.onDisconnect;
+    let onErrorCallback: ((error: Event) => void) | undefined = options.onError;
+    let reconnectTimeout: ReturnType<typeof setTimeout> | null = null;
+    const autoReconnect = options.autoReconnect ?? true;
+    const reconnectDelay = options.reconnectDelay ?? 3000;
+
+    const dispatchEvent = (eventName: string, rawData: string) => {
+      const eventHandlers = handlers.get(eventName);
+      if (!eventHandlers?.size) return;
+
+      let data: any;
+      try {
+        data = JSON.parse(rawData);
+      } catch {
+        data = rawData;
+      }
+
+      for (const handler of eventHandlers) {
+        try {
+          handler(data);
+        } catch (error) {
+          console.error(`Error in SSE event handler for "${eventName}":`, error);
+        }
+      }
+    };
+
+    const scheduleReconnect = () => {
+      if (reconnectTimeout) return;
+      reconnectTimeout = setTimeout(() => {
+        reconnectTimeout = null;
+        // Reconnect by creating new subscription
+        const newSub = this.connectToSSERoute<TEvents>(route, input, options);
+        // Transfer handlers
+        for (const [event, eventHandlers] of handlers) {
+          for (const handler of eventHandlers) {
+            newSub.on(event as keyof TEvents, handler);
+          }
+        }
+      }, reconnectDelay);
+    };
+
+    eventSource.onopen = () => {
+      onConnectCallback?.();
+    };
+
+    eventSource.onerror = (event) => {
+      onErrorCallback?.(event);
+      if (eventSource.readyState === 2) {
+        onDisconnectCallback?.();
+        if (autoReconnect) {
+          scheduleReconnect();
+        }
+      }
+    };
+
+    eventSource.onmessage = (event) => {
+      dispatchEvent("message", event.data);
+    };
+
+    const subscription: SSESubscription<TEvents> = {
+      on: <E extends keyof TEvents>(event: E, handler: (data: TEvents[E]) => void) => {
+        const eventName = String(event);
+        let eventHandlers = handlers.get(eventName);
+        if (!eventHandlers) {
+          eventHandlers = new Set();
+          handlers.set(eventName, eventHandlers);
+          // Add listener to EventSource
+          if (eventName !== "message") {
+            eventSource.addEventListener(eventName, (e) => {
+              if ("data" in e) {
+                dispatchEvent(eventName, (e as SSEMessageEvent).data);
+              }
+            });
+          }
+        }
+        eventHandlers.add(handler as (data: any) => void);
+        return () => {
+          eventHandlers?.delete(handler as (data: any) => void);
+        };
+      },
+      once: <E extends keyof TEvents>(event: E, handler: (data: TEvents[E]) => void) => {
+        const unsubscribe = subscription.on(event, (data) => {
+          unsubscribe();
+          handler(data);
+        });
+        return unsubscribe;
+      },
+      off: <E extends keyof TEvents>(event: E) => {
+        handlers.delete(String(event));
+      },
+      close: () => {
+        if (reconnectTimeout) {
+          clearTimeout(reconnectTimeout);
+          reconnectTimeout = null;
+        }
+        eventSource.close();
+        onDisconnectCallback?.();
+      },
+      get connected() {
+        return eventSource.readyState === 1;
+      },
+    };
+
+    return subscription;
+  }
+
   /**
    * Connect to SSE endpoint for real-time updates
    */

package/src/core/workflows.ts

@@ -11,6 +11,7 @@ import type { Events } from "./events";
 import type { Jobs } from "./jobs";
 import type { SSE } from "./sse";
 import type { z } from "zod";
+import type { CoreServices } from "../core";
 
 // Type helper for Zod schema inference
 type ZodSchema = z.ZodTypeAny;
@@ -192,6 +193,8 @@ export interface WorkflowContext {
   instance: WorkflowInstance;
   /** Get a step result with type safety */
   getStepResult<T = any>(stepName: string): T | undefined;
+  /** Core services (logger, events, cache, etc.) */
+  core: CoreServices;
 }
 
 // ============================================
@@ -501,6 +504,8 @@ export interface WorkflowsConfig {
   sse?: SSE;
   /** Poll interval for checking job completion (ms) */
   pollInterval?: number;
+  /** Core services to pass to step handlers */
+  core?: CoreServices;
 }
 
 export interface Workflows {
@@ -518,6 +523,8 @@ export interface Workflows {
   resume(): Promise<void>;
   /** Stop the workflow service */
   stop(): Promise<void>;
+  /** Set core services (called after initialization to resolve circular dependency) */
+  setCore(core: CoreServices): void;
 }
 
 // ============================================
@@ -529,6 +536,7 @@ class WorkflowsImpl implements Workflows {
   private events?: Events;
   private jobs?: Jobs;
   private sse?: SSE;
+  private core?: CoreServices;
   private definitions = new Map<string, WorkflowDefinition>();
   private running = new Map<string, { timeout?: ReturnType<typeof setTimeout> }>();
   private pollInterval: number;
@@ -538,9 +546,14 @@ class WorkflowsImpl implements Workflows {
     this.events = config.events;
     this.jobs = config.jobs;
     this.sse = config.sse;
+    this.core = config.core;
     this.pollInterval = config.pollInterval ?? 1000;
   }
 
+  setCore(core: CoreServices): void {
+    this.core = core;
+  }
+
   register(definition: WorkflowDefinition): void {
     if (this.definitions.has(definition.name)) {
       throw new Error(`Workflow "${definition.name}" is already registered`);
@@ -1099,6 +1112,7 @@ class WorkflowsImpl implements Workflows {
       getStepResult: <T = any>(stepName: string): T | undefined => {
         return steps[stepName] as T | undefined;
       },
+      core: this.core!,
     };
   }
 

package/src/generator/index.ts

@@ -440,7 +440,7 @@ export function generateClientCode(
     const namespaceName = prefix === "_root" ? "Root" : toPascalCase(prefix);
     const methodName = prefix === "_root" ? "_root" : prefix;
 
-    const typeEntries = prefixRoutes
+    const typedTypeEntries = prefixRoutes
       .filter((r) => r.handler === "typed")
       .map((r) => {
         const inputType = zodToTypeScript(r.inputSource);
@@ -453,6 +453,51 @@ export function generateClientCode(
     export type ${routeNs} = { Input: ${routeNs}.Input; Output: ${routeNs}.Output };`;
       });
 
+    const formDataTypeEntries = prefixRoutes
+      .filter((r) => r.handler === "formData")
+      .map((r) => {
+        const inputType = zodToTypeScript(r.inputSource);
+        const outputType = zodToTypeScript(r.outputSource);
+        const routeNs = toPascalCase(r.routeName);
+        return `    export namespace ${routeNs} {
+      export type Input = ${inputType};
+      export type Output = ${outputType};
+    }
+    export type ${routeNs} = { Input: ${routeNs}.Input; Output: ${routeNs}.Output };`;
+      });
+
+    const streamTypeEntries = prefixRoutes
+      .filter((r) => r.handler === "stream" || r.handler === "html")
+      .map((r) => {
+        const inputType = zodToTypeScript(r.inputSource);
+        const routeNs = toPascalCase(r.routeName);
+        return `    export namespace ${routeNs} {
+      export type Input = ${inputType};
+    }
+    export type ${routeNs} = { Input: ${routeNs}.Input };`;
+      });
+
+    const sseTypeEntries = prefixRoutes
+      .filter((r) => r.handler === "sse")
+      .map((r) => {
+        const inputType = zodToTypeScript(r.inputSource);
+        const routeNs = toPascalCase(r.routeName);
+        // Generate Events type from eventsSource
+        const eventsEntries = r.eventsSource
+          ? Object.entries(r.eventsSource)
+              .map(([eventName, eventType]) => `      "${eventName}": ${zodToTypeScript(eventType)};`)
+              .join("\n")
+          : "";
+        const eventsType = eventsEntries ? `{\n${eventsEntries}\n    }` : "Record<string, unknown>";
+        return `    export namespace ${routeNs} {
+      export type Input = ${inputType};
+      export type Events = ${eventsType};
+    }
+    export type ${routeNs} = { Input: ${routeNs}.Input; Events: ${routeNs}.Events };`;
+      });
+
+    const typeEntries = [...typedTypeEntries, ...formDataTypeEntries, ...streamTypeEntries, ...sseTypeEntries];
+
     if (typeEntries.length > 0) {
       routeTypeBlocks.push(`  export namespace ${namespaceName} {
 ${typeEntries.join("\n\n")}
@@ -475,7 +520,37 @@ ${typeEntries.join("\n\n")}
       this.rawRequest("${r.name}", init)`;
       });
 
-    const allMethods = [...methodEntries, ...rawMethodEntries];
+    const sseMethodEntries = prefixRoutes
+      .filter((r) => r.handler === "sse")
+      .map((r) => {
+        const inputType = r.inputSource
+          ? `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Input`
+          : "Record<string, any>";
+        const eventsType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Events`;
+        return `    ${toCamelCase(r.routeName)}: (input: ${inputType}, options?: Omit<SSEOptions, "endpoint" | "channels">): SSESubscription<${eventsType}> =>
+      this.connectToSSERoute("${r.name}", input, options)`;
+      });
+
+    const streamMethodEntries = prefixRoutes
+      .filter((r) => r.handler === "stream" || r.handler === "html")
+      .map((r) => {
+        const inputType = r.inputSource
+          ? `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Input`
+          : "Record<string, any>";
+        return `    ${toCamelCase(r.routeName)}: (input: ${inputType}): Promise<Response> =>
+      this.streamRequest("${r.name}", input)`;
+      });
+
+    const formDataMethodEntries = prefixRoutes
+      .filter((r) => r.handler === "formData")
+      .map((r) => {
+        const inputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Input`;
+        const outputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Output`;
+        return `    ${toCamelCase(r.routeName)}: (fields: ${inputType}, files?: File[]): Promise<${outputType}> =>
+      this.uploadFormData("${r.name}", fields, files)`;
+      });
+
+    const allMethods = [...methodEntries, ...rawMethodEntries, ...sseMethodEntries, ...streamMethodEntries, ...formDataMethodEntries];
 
     if (allMethods.length > 0) {
       routeNamespaceBlocks.push(`  ${methodName} = {
@@ -512,6 +587,7 @@ import {
   type RequestOptions,
   type ApiClientOptions,
   type SSEOptions,
+  type SSESubscription,
 } from "./base";${additionalImportsStr}
 
 // ============================================
@@ -560,7 +636,7 @@ export function createApiClient(config: ApiClientConfig): ApiClient {
 }
 
 // Re-export base types for convenience
-export { ApiError, ValidationError, type RequestOptions, type SSEOptions };
+export { ApiError, ValidationError, type RequestOptions, type SSEOptions, type SSESubscription };
 `;
 }
 

package/src/server.ts

@@ -166,6 +166,9 @@ export class AppServer {
       websocket,
     };
 
+    // Resolve circular dependency: workflows needs core for step handlers
+    workflows.setCore(this.coreServices);
+
     this.manager = new PluginManager(this.coreServices);
     this.typeGenConfig = options.generateTypes;
   }
@@ -324,9 +327,10 @@ export class AppServer {
       name: string;
       prefix: string;
       routeName: string;
-      handler: "typed" | "raw";
+      handler: "typed" | "raw" | "sse" | "stream" | "formData" | "html";
       inputSource?: string;
       outputSource?: string;
+      eventsSource?: Record<string, string>;
     }> = [];
 
     const routesWithoutOutput: string[] = [];
@@ -342,13 +346,23 @@ export class AppServer {
           routesWithoutOutput.push(route.name);
         }
 
+        // Extract SSE event schemas
+        let eventsSource: Record<string, string> | undefined;
+        if (route.handler === "sse" && route.events) {
+          eventsSource = {};
+          for (const [eventName, eventSchema] of Object.entries(route.events)) {
+            eventsSource[eventName] = zodSchemaToTs(eventSchema as any);
+          }
+        }
+
         routes.push({
           name: route.name,
           prefix,
           routeName,
-          handler: (route.handler || "typed") as "typed" | "raw",
+          handler: (route.handler || "typed") as "typed" | "raw" | "sse" | "stream" | "formData" | "html",
           inputSource: route.input ? zodSchemaToTs(route.input) : undefined,
           outputSource: route.output ? zodSchemaToTs(route.output) : undefined,
+          eventsSource,
         });
       }
     }
@@ -383,9 +397,10 @@ export class AppServer {
       name: string;
       prefix: string;
       routeName: string;
-      handler: "typed" | "raw";
+      handler: "typed" | "raw" | "sse" | "stream" | "formData" | "html";
       inputSource?: string;
       outputSource?: string;
+      eventsSource?: Record<string, string>;
     }>
   ): string {
     const baseImport =
@@ -448,19 +463,43 @@ export function createApi(options?: ClientOptions) {
     // Recursive function to generate Type definitions
     function generateTypeBlock(node: RouteNode, indent: string): string {
       const blocks: string[] = [];
-      
+
       // 1. Valid Input/Output types for routes at this level
       if (node.routes.length > 0) {
         const routeTypes = node.routes.map(r => {
-           if (r.handler !== "typed") return "";
            const routeNs = toPascalCase(r.routeName);
            const inputType = r.inputSource ?? "Record<string, never>";
-           const outputType = r.outputSource ?? "void";
-           return `${indent}export namespace ${routeNs} {
+
+           if (r.handler === "typed" || r.handler === "formData") {
+             // typed and formData have Input and Output
+             const outputType = r.outputSource ?? "void";
+             return `${indent}export namespace ${routeNs} {
 ${indent}  export type Input = Expand<${inputType}>;
 ${indent}  export type Output = Expand<${outputType}>;
 ${indent}}
 ${indent}export type ${routeNs} = { Input: ${routeNs}.Input; Output: ${routeNs}.Output };`;
+           } else if (r.handler === "stream" || r.handler === "html") {
+             // stream and html have Input only (returns Response/string)
+             return `${indent}export namespace ${routeNs} {
+${indent}  export type Input = Expand<${inputType}>;
+${indent}}
+${indent}export type ${routeNs} = { Input: ${routeNs}.Input };`;
+           } else if (r.handler === "sse") {
+             // Generate Events type from eventsSource
+             const eventsEntries = r.eventsSource
+               ? Object.entries(r.eventsSource)
+                   .map(([eventName, eventType]) => `${indent}    "${eventName}": ${eventType};`)
+                   .join("\n")
+               : "";
+             const eventsType = eventsEntries ? `{\n${eventsEntries}\n${indent}  }` : "Record<string, unknown>";
+             return `${indent}export namespace ${routeNs} {
+${indent}  export type Input = Expand<${inputType}>;
+${indent}  export type Events = Expand<${eventsType}>;
+${indent}}
+${indent}export type ${routeNs} = { Input: ${routeNs}.Input; Events: ${routeNs}.Events };`;
+           }
+           // raw handler has no types
+           return "";
         }).filter(Boolean);
         if (routeTypes.length) blocks.push(routeTypes.join("\n\n"));
       }
@@ -481,15 +520,28 @@ ${indent}export type ${routeNs} = { Input: ${routeNs}.Input; Output: ${routeNs}.
       const methods = node.routes.map(r => {
          const methodName = toCamelCase(r.routeName);
          // r.name is the full path e.g. "api.v1.users.get"
-         
+         const pathParts = r.name.split(".");
+         const typePath = ["Routes", ...pathParts.slice(0, -1).map(toPascalCase), toPascalCase(r.routeName)];
+
          if (r.handler === "typed") {
-            const pathParts = r.name.split(".");
-            const typePath = ["Routes", ...pathParts.slice(0, -1).map(toPascalCase), toPascalCase(r.routeName)];
             const inputType = typePath.join(".") + ".Input";
             const outputType = typePath.join(".") + ".Output";
-            
             return `${indent}${methodName}: (input: ${inputType}): Promise<${outputType}> => this.request("${r.name}", input)`;
+         } else if (r.handler === "formData") {
+            const inputType = typePath.join(".") + ".Input";
+            const outputType = typePath.join(".") + ".Output";
+            // formData needs to send multipart form data
+            return `${indent}${methodName}: (fields: ${inputType}, files?: File[]): Promise<${outputType}> => this.uploadFormData("${r.name}", fields, files)`;
+         } else if (r.handler === "stream" || r.handler === "html") {
+            // stream and html have validated input but return Response
+            const inputType = typePath.join(".") + ".Input";
+            return `${indent}${methodName}: (input: ${inputType}): Promise<Response> => this.streamRequest("${r.name}", input)`;
+         } else if (r.handler === "sse") {
+            const inputType = typePath.join(".") + ".Input";
+            const eventsType = typePath.join(".") + ".Events";
+            return `${indent}${methodName}: (input: ${inputType}, options?: Omit<SSEOptions, "endpoint" | "channels">): SSESubscription<${eventsType}> => this.connectToSSERoute("${r.name}", input, options)`;
          } else {
+            // raw handler
             return `${indent}${methodName}: (init?: RequestInit): Promise<Response> => this.rawRequest("${r.name}", init)`;
          }
       });
@@ -515,10 +567,16 @@ ${indent}export type ${routeNs} = { Input: ${routeNs}.Input; Output: ${routeNs}.
     // rootNode children are top-level namespaces (api, health) -> Top Level Class Properties
     const methodBlocks: string[] = [generateMethodBlock(rootNode, "  ", "", true)];
 
+    // Check if we have any SSE routes to know if we need SSE type imports
+    const hasSSERoutes = routes.some(r => r.handler === "sse");
+    const sseImports = hasSSERoutes
+      ? '\nimport { type SSEOptions, type SSESubscription } from "@donkeylabs/server/client";'
+      : "";
+
     return `// Auto-generated by @donkeylabs/server
 // DO NOT EDIT MANUALLY
 
-${baseImport}
+${baseImport}${sseImports}
 
 // Utility type that forces TypeScript to expand types on hover
 type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;