@donkeylabs/adapter-sveltekit 1.0.1 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/adapter-sveltekit",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "type": "module",
   "description": "SvelteKit adapter for @donkeylabs/server - seamless SSR/browser API integration",
   "main": "./src/index.ts",

package/src/client/index.ts

@@ -24,6 +24,116 @@ export interface SSESubscription {
   unsubscribe: () => void;
 }
 
+/**
+ * Type-safe SSE connection wrapper.
+ * Provides typed event handlers with automatic JSON parsing.
+ *
+ * @example
+ * ```ts
+ * const connection = api.notifications.subscribe({ userId: "123" });
+ *
+ * // Typed event handler - returns unsubscribe function
+ * const unsubscribe = connection.on("notification", (data) => {
+ *   console.log(data.message); // Fully typed!
+ * });
+ *
+ * // Later: unsubscribe from this specific handler
+ * unsubscribe();
+ *
+ * // Close entire connection
+ * connection.close();
+ * ```
+ */
+export class SSEConnection<TEvents extends Record<string, any> = Record<string, any>> {
+  private eventSource: EventSource;
+  private handlers = new Map<string, Set<(data: any) => void>>();
+
+  constructor(url: string) {
+    this.eventSource = new EventSource(url);
+  }
+
+  /**
+   * Register a typed event handler.
+   * @returns Unsubscribe function to remove this specific handler
+   */
+  on<K extends keyof TEvents>(
+    event: K & string,
+    handler: (data: TEvents[K]) => void
+  ): () => void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+
+      // Add EventSource listener for this event type
+      this.eventSource.addEventListener(event, (e: MessageEvent) => {
+        const handlers = this.handlers.get(event);
+        if (handlers) {
+          let data: any;
+          try {
+            data = JSON.parse(e.data);
+          } catch {
+            data = e.data;
+          }
+          for (const h of handlers) {
+            h(data);
+          }
+        }
+      });
+    }
+
+    this.handlers.get(event)!.add(handler);
+
+    // Return unsubscribe function
+    return () => {
+      const handlers = this.handlers.get(event);
+      if (handlers) {
+        handlers.delete(handler);
+      }
+    };
+  }
+
+  /**
+   * Register error handler
+   */
+  onError(handler: (event: Event) => void): () => void {
+    this.eventSource.onerror = handler;
+    return () => {
+      this.eventSource.onerror = null;
+    };
+  }
+
+  /**
+   * Register open handler (connection established)
+   */
+  onOpen(handler: (event: Event) => void): () => void {
+    this.eventSource.onopen = handler;
+    return () => {
+      this.eventSource.onopen = null;
+    };
+  }
+
+  /**
+   * Get connection state
+   */
+  get readyState(): number {
+    return this.eventSource.readyState;
+  }
+
+  /**
+   * Check if connected
+   */
+  get connected(): boolean {
+    return this.eventSource.readyState === EventSource.OPEN;
+  }
+
+  /**
+   * Close the SSE connection
+   */
+  close(): void {
+    this.eventSource.close();
+    this.handlers.clear();
+  }
+}
+
 /**
  * Base class for unified API clients.
  * Extend this class with your generated route methods.
@@ -104,6 +214,176 @@ export class UnifiedApiClientBase {
     });
   }
 
+  /**
+   * Make a stream request (validated input, Response output).
+   * For streaming, binary data, or custom content-type responses.
+   *
+   * By default uses POST with JSON body. For browser compatibility
+   * (video src, image src, download links), use streamUrl() instead.
+   */
+  protected async streamRequest<TInput>(
+    route: string,
+    input: TInput,
+    options?: RequestOptions
+  ): Promise<Response> {
+    const url = `${this.baseUrl}/${route}`;
+    const fetchFn = this.customFetch ?? fetch;
+
+    const response = await fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...options?.headers,
+      },
+      body: JSON.stringify(input),
+      signal: options?.signal,
+    });
+
+    // Unlike typed requests, we return the raw Response
+    // Error handling is left to the caller
+    return response;
+  }
+
+  /**
+   * Get the URL for a stream endpoint (for browser src attributes).
+   * Returns a URL with query params that can be used in:
+   * - <video src={url}>
+   * - <img src={url}>
+   * - <a href={url} download>
+   * - window.open(url)
+   */
+  protected streamUrl<TInput>(route: string, input?: TInput): string {
+    let url = `${this.baseUrl}/${route}`;
+
+    if (input && typeof input === "object") {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(input)) {
+        params.set(key, typeof value === "string" ? value : JSON.stringify(value));
+      }
+      url += `?${params.toString()}`;
+    }
+
+    return url;
+  }
+
+  /**
+   * Fetch a stream via GET with query params.
+   * Alternative to streamRequest() for cases where GET is preferred.
+   */
+  protected async streamGet<TInput>(
+    route: string,
+    input?: TInput,
+    options?: RequestOptions
+  ): Promise<Response> {
+    const url = this.streamUrl(route, input);
+    const fetchFn = this.customFetch ?? fetch;
+
+    return fetchFn(url, {
+      method: "GET",
+      headers: options?.headers,
+      signal: options?.signal,
+    });
+  }
+
+  /**
+   * Connect to an SSE endpoint.
+   * Returns a typed SSEConnection for handling server-sent events.
+   */
+  protected sseConnect<TInput, TEvents extends Record<string, any> = Record<string, any>>(
+    route: string,
+    input?: TInput
+  ): SSEConnection<TEvents> {
+    let url = `${this.baseUrl}/${route}`;
+
+    // Add input as query params for GET request
+    if (input && typeof input === "object") {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(input)) {
+        params.set(key, typeof value === "string" ? value : JSON.stringify(value));
+      }
+      url += `?${params.toString()}`;
+    }
+
+    return new SSEConnection<TEvents>(url);
+  }
+
+  /**
+   * Make a formData request (file uploads with validated fields).
+   */
+  protected async formDataRequest<TFields, TOutput>(
+    route: string,
+    fields: TFields,
+    files: File[],
+    options?: RequestOptions
+  ): Promise<TOutput> {
+    const url = `${this.baseUrl}/${route}`;
+    const fetchFn = this.customFetch ?? fetch;
+
+    const formData = new FormData();
+
+    // Add fields
+    if (fields && typeof fields === "object") {
+      for (const [key, value] of Object.entries(fields)) {
+        formData.append(key, typeof value === "string" ? value : JSON.stringify(value));
+      }
+    }
+
+    // Add files
+    for (const file of files) {
+      formData.append("file", file);
+    }
+
+    const response = await fetchFn(url, {
+      method: "POST",
+      headers: options?.headers,
+      body: formData,
+      signal: options?.signal,
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: "Unknown error" }));
+      throw new Error(error.message || error.error || `HTTP ${response.status}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Make an HTML request (returns HTML string).
+   */
+  protected async htmlRequest<TInput>(
+    route: string,
+    input?: TInput,
+    options?: RequestOptions
+  ): Promise<string> {
+    let url = `${this.baseUrl}/${route}`;
+    const fetchFn = this.customFetch ?? fetch;
+
+    // Add input as query params for GET request
+    if (input && typeof input === "object") {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(input)) {
+        params.set(key, typeof value === "string" ? value : JSON.stringify(value));
+      }
+      url += `?${params.toString()}`;
+    }
+
+    const response = await fetchFn(url, {
+      method: "GET",
+      headers: {
+        Accept: "text/html",
+        ...options?.headers,
+      },
+      signal: options?.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+
+    return response.text();
+  }
+
   /**
    * SSE (Server-Sent Events) subscription.
    * Only works in the browser.

package/src/generator/index.ts

@@ -33,7 +33,7 @@ function isRouteInfo(route: RouteInfo | ExtractedRoute): route is RouteInfo {
 /** SvelteKit-specific generator options */
 export const svelteKitGeneratorOptions: ClientGeneratorOptions = {
   baseImport:
-    'import { UnifiedApiClientBase, type ClientOptions } from "@donkeylabs/adapter-sveltekit/client";',
+    'import { UnifiedApiClientBase, SSEConnection, type ClientOptions } from "@donkeylabs/adapter-sveltekit/client";',
   baseClass: "UnifiedApiClientBase",
   constructorSignature: "options?: ClientOptions",
   constructorBody: "super(options);",
@@ -114,9 +114,9 @@ function generateTypedSvelteKitClient(routes: RouteInfo[]): string {
     const pascalNs = namespace === "_root" ? "Root" : toPascalCase(namespace);
     const methodNs = namespace === "_root" ? "_root" : namespace;
 
-    // Generate types for this namespace
+    // Generate types for this namespace (typed, stream, sse, formData, html routes have input types)
     const typeEntries = nsRoutes
-      .filter(r => r.handler === "typed")
+      .filter(r => ["typed", "stream", "sse", "formData", "html"].includes(r.handler))
       .map(r => {
         const pascalRoute = toPascalCase(r.routeName);
         // If inputSource starts with "z.", it's a Zod source string - convert it
@@ -124,6 +124,36 @@ function generateTypedSvelteKitClient(routes: RouteInfo[]): string {
         const inputType = r.inputSource
           ? (r.inputSource.trim().startsWith("z.") ? zodToTypeScript(r.inputSource) : r.inputSource)
           : "Record<string, never>";
+
+        // Handlers that don't have typed output (return Response or string directly)
+        if (r.handler === "stream" || r.handler === "html") {
+          return `    export namespace ${pascalRoute} {
+      export type Input = Expand<${inputType}>;
+    }
+    export type ${pascalRoute} = { Input: ${pascalRoute}.Input };`;
+        }
+
+        // SSE routes - include Events type if eventsSource is present
+        if (r.handler === "sse") {
+          const eventsEntries = r.eventsSource
+            ? Object.entries(r.eventsSource).map(([eventName, eventSchema]) => {
+                const eventType = eventSchema.trim().startsWith("z.")
+                  ? zodToTypeScript(eventSchema)
+                  : eventSchema;
+                return `        "${eventName}": Expand<${eventType}>;`;
+              })
+            : [];
+          const eventsType = eventsEntries.length > 0
+            ? `{\n${eventsEntries.join("\n")}\n      }`
+            : "Record<string, unknown>";
+          return `    export namespace ${pascalRoute} {
+      export type Input = Expand<${inputType}>;
+      export type Events = ${eventsType};
+    }
+    export type ${pascalRoute} = { Input: ${pascalRoute}.Input; Events: ${pascalRoute}.Events };`;
+        }
+
+        // typed and formData have both Input and Output
         const outputType = r.outputSource
           ? (r.outputSource.trim().startsWith("z.") ? zodToTypeScript(r.outputSource) : r.outputSource)
           : "unknown";
@@ -159,7 +189,63 @@ function generateTypedSvelteKitClient(routes: RouteInfo[]): string {
         return `    ${methodName}: (init?: RequestInit): Promise<Response> => this.rawRequest("${fullRouteName}", init)`;
       });
 
-    const allMethods = [...methodEntries, ...rawMethodEntries];
+    const streamMethodEntries = nsRoutes
+      .filter(r => r.handler === "stream")
+      .map(r => {
+        const methodName = toCamelCase(r.routeName);
+        const pascalRoute = toPascalCase(r.routeName);
+        const inputType = `Routes.${pascalNs}.${pascalRoute}.Input`;
+        const fullRouteName = commonPrefix ? `${commonPrefix}.${r.name}` : r.name;
+        // Stream routes provide three methods:
+        // - fetch(input): POST request (programmatic)
+        // - url(input): GET URL for browser (video src, img src, download links)
+        // - get(input): GET fetch request
+        return `    ${methodName}: {
+      /** POST request with JSON body (programmatic) */
+      fetch: (input: ${inputType}): Promise<Response> => this.streamRequest("${fullRouteName}", input),
+      /** GET URL for browser src attributes (video, img, download links) */
+      url: (input: ${inputType}): string => this.streamUrl("${fullRouteName}", input),
+      /** GET request with query params */
+      get: (input: ${inputType}): Promise<Response> => this.streamGet("${fullRouteName}", input),
+    }`;
+      });
+
+    const sseMethodEntries = nsRoutes
+      .filter(r => r.handler === "sse")
+      .map(r => {
+        const methodName = toCamelCase(r.routeName);
+        const pascalRoute = toPascalCase(r.routeName);
+        const hasInput = r.inputSource;
+        const inputType = hasInput ? `Routes.${pascalNs}.${pascalRoute}.Input` : "Record<string, never>";
+        const eventsType = `Routes.${pascalNs}.${pascalRoute}.Events`;
+        const fullRouteName = commonPrefix ? `${commonPrefix}.${r.name}` : r.name;
+        // SSE returns typed SSEConnection for type-safe event handling
+        return `    ${methodName}: (${hasInput ? `input: ${inputType}` : ""}): SSEConnection<${eventsType}> => this.sseConnect("${fullRouteName}"${hasInput ? ", input" : ""})`;
+      });
+
+    const formDataMethodEntries = nsRoutes
+      .filter(r => r.handler === "formData")
+      .map(r => {
+        const methodName = toCamelCase(r.routeName);
+        const pascalRoute = toPascalCase(r.routeName);
+        const inputType = r.inputSource ? `Routes.${pascalNs}.${pascalRoute}.Input` : "Record<string, any>";
+        const outputType = r.outputSource ? `Routes.${pascalNs}.${pascalRoute}.Output` : "unknown";
+        const fullRouteName = commonPrefix ? `${commonPrefix}.${r.name}` : r.name;
+        return `    ${methodName}: (fields: ${inputType}, files: File[]): Promise<${outputType}> => this.formDataRequest("${fullRouteName}", fields, files)`;
+      });
+
+    const htmlMethodEntries = nsRoutes
+      .filter(r => r.handler === "html")
+      .map(r => {
+        const methodName = toCamelCase(r.routeName);
+        const pascalRoute = toPascalCase(r.routeName);
+        const hasInput = r.inputSource;
+        const inputType = hasInput ? `Routes.${pascalNs}.${pascalRoute}.Input` : "Record<string, never>";
+        const fullRouteName = commonPrefix ? `${commonPrefix}.${r.name}` : r.name;
+        return `    ${methodName}: (${hasInput ? `input: ${inputType}` : ""}): Promise<string> => this.htmlRequest("${fullRouteName}"${hasInput ? ", input" : ""})`;
+      });
+
+    const allMethods = [...methodEntries, ...rawMethodEntries, ...streamMethodEntries, ...sseMethodEntries, ...formDataMethodEntries, ...htmlMethodEntries];
     if (allMethods.length > 0) {
       if (namespace === "_root") {
         // Root-level methods go directly on the class

package/src/vite.ts

@@ -112,13 +112,14 @@ export function donkeylabsDev(options: DevPluginOptions = {}): Plugin {
           // In-process request handler
           const inProcessMiddleware = async (req: any, res: any, next: any) => {
             const url = req.url || "/";
+            const urlObj = new URL(url, "http://localhost");
+            const pathname = urlObj.pathname;
 
-            // Handle SSE
-            if (req.method === "GET" && url.startsWith("/sse")) {
+            // Handle SSE endpoint
+            if (req.method === "GET" && pathname === "/sse") {
               if (!serverReady || !appServer) return next();
 
-              const fullUrl = new URL(url, "http://localhost");
-              const channels = fullUrl.searchParams.get("channels")?.split(",").filter(Boolean) || [];
+              const channels = urlObj.searchParams.get("channels")?.split(",").filter(Boolean) || [];
               const lastEventId = req.headers["last-event-id"] || undefined;
 
               const { client, response } = appServer.getCore().sse.addClient({ lastEventId });
@@ -159,32 +160,91 @@ export function donkeylabsDev(options: DevPluginOptions = {}): Plugin {
               return; // Don't call next()
             }
 
-            // Handle API routes (POST only)
-            if (req.method === "POST" && /^\/[a-zA-Z][a-zA-Z0-9_.]*$/.test(url)) {
+            // Handle API routes (GET or POST for route names like /routeName.action)
+            if ((req.method === "GET" || req.method === "POST") && /^\/[a-zA-Z][a-zA-Z0-9_.]*$/.test(pathname)) {
               if (!serverReady || !appServer) return next();
 
-              const routeName = url.slice(1);
+              const routeName = pathname.slice(1);
               if (!appServer.hasRoute(routeName)) return next();
 
-              // Collect body
-              let body = "";
-              req.on("data", (chunk: any) => (body += chunk));
-              req.on("end", async () => {
-                try {
-                  const input = body ? JSON.parse(body) : {};
-                  const ip = req.socket?.remoteAddress || "127.0.0.1";
+              // Build a proper Request object to pass to handleRequest
+              const buildRequest = async (): Promise<Request> => {
+                const fullUrl = `http://localhost${url}`;
+                const headers = new Headers();
+                for (const [key, value] of Object.entries(req.headers)) {
+                  if (typeof value === "string") {
+                    headers.set(key, value);
+                  } else if (Array.isArray(value)) {
+                    for (const v of value) headers.append(key, v);
+                  }
+                }
+
+                if (req.method === "POST") {
+                  // Collect body for POST
+                  const chunks: Buffer[] = [];
+                  for await (const chunk of req) {
+                    chunks.push(chunk);
+                  }
+                  const body = Buffer.concat(chunks);
+                  return new Request(fullUrl, {
+                    method: "POST",
+                    headers,
+                    body,
+                  });
+                }
 
-                  const result = await appServer.callRoute(routeName, input, ip);
+                return new Request(fullUrl, { method: "GET", headers });
+              };
 
-                  res.setHeader("Content-Type", "application/json");
-                  res.setHeader("Access-Control-Allow-Origin", "*");
-                  res.end(JSON.stringify(result));
-                } catch (err: any) {
-                  res.statusCode = err.status || 500;
-                  res.setHeader("Content-Type", "application/json");
-                  res.end(JSON.stringify({ error: err.message || "Internal error" }));
+              try {
+                const request = await buildRequest();
+                const ip = req.socket?.remoteAddress || "127.0.0.1";
+
+                // Use handleRequest which properly handles all handler types (typed, raw, stream, sse, html)
+                const response = await appServer.handleRequest(
+                  request,
+                  routeName,
+                  ip,
+                  { corsHeaders: { "Access-Control-Allow-Origin": "*" } }
+                );
+
+                if (!response) {
+                  return next();
                 }
-              });
+
+                // Stream the response back
+                res.statusCode = response.status;
+                for (const [key, value] of response.headers) {
+                  res.setHeader(key, value);
+                }
+
+                // Handle body streaming
+                if (response.body) {
+                  const reader = response.body.getReader();
+                  const pump = async () => {
+                    try {
+                      while (true) {
+                        const { done, value } = await reader.read();
+                        if (done) {
+                          res.end();
+                          break;
+                        }
+                        res.write(value);
+                      }
+                    } catch {
+                      res.end();
+                    }
+                  };
+                  await pump();
+                } else {
+                  res.end();
+                }
+              } catch (err: any) {
+                console.error("[donkeylabs-dev] Request error:", err);
+                res.statusCode = err.status || 500;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({ error: err.message || "Internal error" }));
+              }
 
               return; // Don't call next()
             }
@@ -286,10 +346,13 @@ export function donkeylabsDev(options: DevPluginOptions = {}): Plugin {
             }, 10000);
           });
 
-          // Proxy middleware
+          // Proxy middleware - handles GET and POST for API routes
           const proxyMiddleware = (req: any, res: any, next: any) => {
             const url = req.url || "/";
-            const isApiRoute = req.method === "POST" && /^\/[a-zA-Z][a-zA-Z0-9_.]*$/.test(url);
+            const urlObj = new URL(url, "http://localhost");
+            const pathname = urlObj.pathname;
+            // API routes are GET or POST to paths like /routeName.action
+            const isApiRoute = (req.method === "GET" || req.method === "POST") && /^\/[a-zA-Z][a-zA-Z0-9_.]*$/.test(pathname);
 
             if (!isApiRoute) return next();
 
@@ -298,7 +361,7 @@ export function donkeylabsDev(options: DevPluginOptions = {}): Plugin {
                 {
                   hostname: "localhost",
                   port: backendPort,
-                  path: url,
+                  path: url, // Include query string
                   method: req.method,
                   headers: { ...req.headers, host: `localhost:${backendPort}` },
                 },
@@ -308,6 +371,7 @@ export function donkeylabsDev(options: DevPluginOptions = {}): Plugin {
                   for (const [k, v] of Object.entries(proxyRes.headers)) {
                     if (v) res.setHeader(k, v);
                   }
+                  // Stream response back (works for binary/streaming responses)
                   proxyRes.pipe(res);
                 }
               );
@@ -318,7 +382,12 @@ export function donkeylabsDev(options: DevPluginOptions = {}): Plugin {
                 res.end(JSON.stringify({ error: "Backend unavailable" }));
               });
 
-              req.pipe(proxyReq);
+              // For POST, pipe the body; for GET, just end
+              if (req.method === "POST") {
+                req.pipe(proxyReq);
+              } else {
+                proxyReq.end();
+              }
             });
           };