@donkeylabs/server 0.1.1 → 0.1.2

package/docs/svelte-frontend.md

@@ -0,0 +1,324 @@
+# Svelte 5 Frontend
+
+Guide for building Svelte 5 frontends with the generated API client.
+
+## Setup
+
+### Create SvelteKit App
+
+```sh
+bunx sv create frontend
+cd frontend
+bun install
+```
+
+### Generate API Client
+
+From your server project:
+
+```sh
+bun run gen:client --output ../frontend/src/lib/api
+```
+
+This creates `frontend/src/lib/api/index.ts` with typed methods.
+
+---
+
+## Basic Usage
+
+### Initialize Client
+
+```ts
+// src/lib/api.ts
+import { createApiClient } from "./api";
+
+export const api = createApiClient({
+  baseUrl: "http://localhost:3000",
+});
+```
+
+### Use in Components
+
+```svelte
+<script lang="ts">
+  import { api } from "$lib/api";
+
+  let items = $state<Item[]>([]);
+  let loading = $state(true);
+  let error = $state<string | null>(null);
+
+  async function load() {
+    try {
+      const result = await api.items.list({});
+      items = result.items;
+    } catch (e) {
+      error = e instanceof Error ? e.message : "Failed to load";
+    } finally {
+      loading = false;
+    }
+  }
+
+  $effect(() => {
+    load();
+  });
+</script>
+
+{#if loading}
+  <p>Loading...</p>
+{:else if error}
+  <p class="error">{error}</p>
+{:else}
+  <ul>
+    {#each items as item (item.id)}
+      <li>{item.name}</li>
+    {/each}
+  </ul>
+{/if}
+```
+
+---
+
+## Svelte 5 Patterns
+
+### State with $state
+
+```svelte
+<script lang="ts">
+  // Reactive state
+  let count = $state(0);
+  let user = $state<User | null>(null);
+  let items = $state<Item[]>([]);
+
+  // Derived values
+  let doubled = $derived(count * 2);
+  let hasItems = $derived(items.length > 0);
+</script>
+```
+
+### Effects with $effect
+
+```svelte
+<script lang="ts">
+  let id = $state(1);
+
+  // Runs when id changes
+  $effect(() => {
+    loadUser(id);
+  });
+
+  // Cleanup pattern
+  $effect(() => {
+    const interval = setInterval(refresh, 5000);
+    return () => clearInterval(interval);
+  });
+</script>
+```
+
+### Form Handling
+
+```svelte
+<script lang="ts">
+  let title = $state("");
+  let submitting = $state(false);
+
+  async function handleSubmit(e: SubmitEvent) {
+    e.preventDefault();
+    if (!title.trim()) return;
+
+    submitting = true;
+    try {
+      await api.items.create({ title });
+      title = "";
+      await load(); // Refresh list
+    } catch (e) {
+      error = e instanceof Error ? e.message : "Failed to create";
+    } finally {
+      submitting = false;
+    }
+  }
+</script>
+
+<form onsubmit={handleSubmit}>
+  <input bind:value={title} placeholder="Title" />
+  <button disabled={submitting}>
+    {submitting ? "Creating..." : "Create"}
+  </button>
+</form>
+```
+
+---
+
+## Real-time Updates (SSE)
+
+### Connect on Mount
+
+```svelte
+<script lang="ts">
+  import { api } from "$lib/api";
+  import { onMount } from "svelte";
+
+  let items = $state<Item[]>([]);
+
+  onMount(() => {
+    // Connect to SSE
+    api.connect();
+
+    // Listen for updates
+    const unsubscribe = api.on("items.changed", (data) => {
+      if (data.action === "created") {
+        items = [data.item, ...items];
+      } else if (data.action === "deleted") {
+        items = items.filter((i) => i.id !== data.item.id);
+      }
+    });
+
+    // Cleanup
+    return () => {
+      unsubscribe();
+      api.disconnect();
+    };
+  });
+</script>
+```
+
+### Connection Status
+
+```svelte
+<script lang="ts">
+  let connected = $state(false);
+
+  onMount(() => {
+    api.connect({
+      onConnect: () => (connected = true),
+      onDisconnect: () => (connected = false),
+    });
+
+    return () => api.disconnect();
+  });
+</script>
+
+<span class={connected ? "online" : "offline"}>
+  {connected ? "Connected" : "Disconnected"}
+</span>
+```
+
+---
+
+## Error Handling
+
+```svelte
+<script lang="ts">
+  import { ApiError, ValidationError } from "$lib/api";
+
+  async function save() {
+    try {
+      await api.items.create({ title });
+    } catch (e) {
+      if (e instanceof ValidationError) {
+        // Show field errors
+        errors = e.details; // [{ path: ["title"], message: "Required" }]
+      } else if (e instanceof ApiError) {
+        if (e.status === 404) {
+          error = "Not found";
+        } else if (e.status === 401) {
+          goto("/login");
+        } else {
+          error = e.body?.message || "Server error";
+        }
+      }
+    }
+  }
+</script>
+```
+
+---
+
+## Complete Example
+
+```svelte
+<!-- src/routes/+page.svelte -->
+<script lang="ts">
+  import { api, type Item } from "$lib/api";
+  import { onMount } from "svelte";
+
+  let items = $state<Item[]>([]);
+  let loading = $state(true);
+  let error = $state<string | null>(null);
+  let newTitle = $state("");
+
+  async function load() {
+    try {
+      const result = await api.items.list({});
+      items = result.items;
+    } catch (e) {
+      error = e instanceof Error ? e.message : "Failed to load";
+    } finally {
+      loading = false;
+    }
+  }
+
+  async function create() {
+    if (!newTitle.trim()) return;
+    try {
+      await api.items.create({ title: newTitle });
+      newTitle = "";
+      await load();
+    } catch (e) {
+      error = e instanceof Error ? e.message : "Failed to create";
+    }
+  }
+
+  async function remove(id: number) {
+    try {
+      await api.items.delete({ id });
+      items = items.filter((i) => i.id !== id);
+    } catch (e) {
+      error = e instanceof Error ? e.message : "Failed to delete";
+    }
+  }
+
+  onMount(() => {
+    load();
+  });
+</script>
+
+<main>
+  <h1>Items</h1>
+
+  {#if error}
+    <p class="error">{error}</p>
+  {/if}
+
+  <form onsubmit={(e) => { e.preventDefault(); create(); }}>
+    <input bind:value={newTitle} placeholder="New item" />
+    <button>Add</button>
+  </form>
+
+  {#if loading}
+    <p>Loading...</p>
+  {:else}
+    <ul>
+      {#each items as item (item.id)}
+        <li>
+          {item.title}
+          <button onclick={() => remove(item.id)}>Delete</button>
+        </li>
+      {/each}
+    </ul>
+  {/if}
+</main>
+
+<style>
+  .error { color: red; }
+</style>
+```
+
+---
+
+## Guidelines
+
+- **Keep components focused** - one concern per component
+- **Handle loading states** - always show loading/error feedback
+- **Clean up on unmount** - disconnect SSE, clear intervals
+- **Use $derived for computed values** - not $state
+- **Type your state** - `$state<Type[]>([])` not `$state([])`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",
@@ -27,9 +27,10 @@
     "src",
     "cli",
     "mcp",
+    "docs",
     "templates",
-    "cli/donkeylabs",
-    "mcp/donkeylabs-mcp"
+    "context.d.ts",
+    "registry.d.ts"
   ],
   "scripts": {
     "gen:registry": "bun scripts/generate-registry.ts",
@@ -45,18 +46,20 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@types/prompts": "^2.4.9",
-    "kysely-codegen": "^0.19.0"
+    "kysely": "^0.27.6",
+    "kysely-bun-sqlite": "^0.3.2",
+    "kysely-codegen": "^0.19.0",
+    "zod": "^3.24.0"
   },
   "peerDependencies": {
-    "typescript": "^5"
+    "typescript": "^5",
+    "kysely": "^0.27.0 || ^0.28.0",
+    "zod": "^3.20.0"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
-    "kysely": "^0.28.9",
-    "kysely-bun-sqlite": "^0.4.0",
     "picocolors": "^1.1.1",
-    "prompts": "^2.4.2",
-    "zod": "^4.3.5"
+    "prompts": "^2.4.2"
   },
   "keywords": [
     "api",

package/registry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Plugin and handler registry.
+ * This is a stub - run `donkeylabs generate` to create project-specific types.
+ */
+
+// Extend PluginHandlerRegistry in your project's generated types
+declare module "./src/core" {
+  interface PluginHandlerRegistry {}
+}
+
+export {};

package/src/index.ts

@@ -22,7 +22,7 @@ export {
 } from "./core";
 
 // Middleware
-export { createMiddleware, composeMiddleware } from "./middleware";
+export { createMiddleware } from "./middleware";
 
 // Config helper
 export function defineConfig(config: {

package/src/server.ts

@@ -190,6 +190,7 @@ export class AppServer {
           plugins: this.manager.getServices(),
           core: this.coreServices,
           errors: this.coreServices.errors,
+          config: this.coreServices.config,
           ip,
           requestId: crypto.randomUUID(),
         };