@tanstack/ai-svelte 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @tanstack/ai-svelte
+
+Svelte bindings for TanStack AI.
+
+## Installation
+
+```bash
+npm install @tanstack/ai-svelte
+# or
+pnpm add @tanstack/ai-svelte
+# or
+yarn add @tanstack/ai-svelte
+```
+
+## Usage
+
+```svelte
+<script>
+  import { createChat, fetchServerSentEvents } from '@tanstack/ai-svelte'
+
+  const chat = createChat({
+    connection: fetchServerSentEvents('/api/chat'),
+  })
+</script>
+
+<div>
+  {#each chat.messages as message}
+    <div>{message.role}: {message.parts[0].content}</div>
+  {/each}
+
+  {#if chat.isLoading}
+    <button onclick={chat.stop}>Stop</button>
+  {/if}
+
+  <button onclick={() => chat.sendMessage('Hello!')}> Send </button>
+</div>
+```
+
+## API
+
+### `createChat(options)`
+
+Creates a reactive chat instance. Returns an object with reactive getters and methods:
+
+**Reactive Properties (no `$` prefix needed):**
+
+- `messages` - Array of messages in the conversation
+- `isLoading` - Boolean indicating if a response is being generated
+- `error` - Current error, if any
+
+**Methods:**
+
+- `sendMessage(content)` - Send a message
+- `append(message)` - Append a message
+- `reload()` - Reload the last assistant message
+- `stop()` - Stop the current response generation
+- `clear()` - Clear all messages
+- `setMessages(messages)` - Set messages manually
+- `addToolResult(result)` - Add a tool result
+- `addToolApprovalResponse(response)` - Respond to a tool approval request
+
+## Svelte 5 Runes
+
+This library uses Svelte 5 runes (`$state`) internally, providing a clean API where you don't need to use the `$` prefix to access reactive state:
+
+```svelte
+<script>
+  const chat = createChat({ ... })
+  
+  // No $ needed - these are reactive getters!
+  console.log(chat.messages)
+  console.log(chat.isLoading)
+</script>
+
+<!-- Reactivity works automatically in templates -->
+{#each chat.messages as message}
+  ...
+{/each}
+```
+
+## License
+
+MIT

package/dist/create-chat.svelte.d.ts

@@ -0,0 +1,33 @@
+import type { AnyClientTool } from '@tanstack/ai';
+import type { CreateChatOptions, CreateChatReturn } from './types';
+/**
+ * Creates a reactive chat instance for Svelte 5.
+ *
+ * This function wraps the ChatClient from @tanstack/ai-client and exposes
+ * reactive state using Svelte 5 runes. The returned object has reactive
+ * getters that automatically update when state changes.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createChat, fetchServerSentEvents } from '@tanstack/ai-svelte'
+ *
+ *   const chat = createChat({
+ *     connection: fetchServerSentEvents('/api/chat'),
+ *   })
+ * </script>
+ *
+ * <div>
+ *   {#each chat.messages as message}
+ *     <div>{message.role}: {message.parts[0].content}</div>
+ *   {/each}
+ *
+ *   {#if chat.isLoading}
+ *     <button onclick={chat.stop}>Stop</button>
+ *   {/if}
+ *
+ *   <button onclick={() => chat.sendMessage('Hello!')}>Send</button>
+ * </div>
+ * ```
+ */
+export declare function createChat<TTools extends ReadonlyArray<AnyClientTool> = any>(options: CreateChatOptions<TTools>): CreateChatReturn<TTools>;

package/dist/create-chat.svelte.js

@@ -0,0 +1,108 @@
+import { ChatClient } from '@tanstack/ai-client';
+/**
+ * Creates a reactive chat instance for Svelte 5.
+ *
+ * This function wraps the ChatClient from @tanstack/ai-client and exposes
+ * reactive state using Svelte 5 runes. The returned object has reactive
+ * getters that automatically update when state changes.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createChat, fetchServerSentEvents } from '@tanstack/ai-svelte'
+ *
+ *   const chat = createChat({
+ *     connection: fetchServerSentEvents('/api/chat'),
+ *   })
+ * </script>
+ *
+ * <div>
+ *   {#each chat.messages as message}
+ *     <div>{message.role}: {message.parts[0].content}</div>
+ *   {/each}
+ *
+ *   {#if chat.isLoading}
+ *     <button onclick={chat.stop}>Stop</button>
+ *   {/if}
+ *
+ *   <button onclick={() => chat.sendMessage('Hello!')}>Send</button>
+ * </div>
+ * ```
+ */
+export function createChat(options) {
+    // Generate a unique ID for this chat instance
+    const clientId = options.id ||
+        `chat-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+    // Create reactive state using Svelte 5 runes
+    let messages = $state(options.initialMessages || []);
+    let isLoading = $state(false);
+    let error = $state(undefined);
+    // Create ChatClient instance
+    const client = new ChatClient({
+        connection: options.connection,
+        id: clientId,
+        initialMessages: options.initialMessages,
+        body: options.body,
+        onResponse: options.onResponse,
+        onChunk: options.onChunk,
+        onFinish: options.onFinish,
+        onError: options.onError,
+        tools: options.tools,
+        streamProcessor: options.streamProcessor,
+        onMessagesChange: (newMessages) => {
+            messages = newMessages;
+        },
+        onLoadingChange: (newIsLoading) => {
+            isLoading = newIsLoading;
+        },
+        onErrorChange: (newError) => {
+            error = newError;
+        },
+    });
+    // Define methods
+    const sendMessage = async (content) => {
+        await client.sendMessage(content);
+    };
+    const append = async (message) => {
+        await client.append(message);
+    };
+    const reload = async () => {
+        await client.reload();
+    };
+    const stop = () => {
+        client.stop();
+    };
+    const clear = () => {
+        client.clear();
+    };
+    const setMessages = (newMessages) => {
+        client.setMessagesManually(newMessages);
+    };
+    const addToolResult = async (result) => {
+        await client.addToolResult(result);
+    };
+    const addToolApprovalResponse = async (response) => {
+        await client.addToolApprovalResponse(response);
+    };
+    // Return the chat interface with reactive getters
+    // Using getters allows Svelte to track reactivity without needing $ prefix
+    return {
+        get messages() {
+            return messages;
+        },
+        get isLoading() {
+            return isLoading;
+        },
+        get error() {
+            return error;
+        },
+        sendMessage,
+        append,
+        reload,
+        stop,
+        setMessages,
+        clear,
+        addToolResult,
+        addToolApprovalResponse,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createChat } from './create-chat.svelte';
+export type { CreateChatOptions, CreateChatReturn, UIMessage, ChatRequestBody, } from './types';
+export { fetchServerSentEvents, fetchHttpStream, stream, createChatClientOptions, clientTools, type ConnectionAdapter, type FetchConnectionOptions, type InferChatMessages, } from '@tanstack/ai-client';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createChat } from './create-chat.svelte';
+// Re-export from ai-client for convenience
+export { fetchServerSentEvents, fetchHttpStream, stream, createChatClientOptions, clientTools, } from '@tanstack/ai-client';

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+import type { AnyClientTool, ModelMessage } from '@tanstack/ai';
+import type { ChatClientOptions, ChatRequestBody, UIMessage } from '@tanstack/ai-client';
+export type { UIMessage, ChatRequestBody };
+/**
+ * Options for the createChat function.
+ *
+ * This extends ChatClientOptions but omits the state change callbacks that are
+ * managed internally by Svelte state:
+ * - `onMessagesChange` - Managed by Svelte state (exposed as `messages`)
+ * - `onLoadingChange` - Managed by Svelte state (exposed as `isLoading`)
+ * - `onErrorChange` - Managed by Svelte state (exposed as `error`)
+ *
+ * All other callbacks (onResponse, onChunk, onFinish, onError) are
+ * passed through to the underlying ChatClient and can be used for side effects.
+ *
+ * Note: Connection and body changes will recreate the ChatClient instance.
+ * To update these options, remount the component or use a key prop.
+ */
+export type CreateChatOptions<TTools extends ReadonlyArray<AnyClientTool> = any> = Omit<ChatClientOptions<TTools>, 'onMessagesChange' | 'onLoadingChange' | 'onErrorChange'>;
+export interface CreateChatReturn<TTools extends ReadonlyArray<AnyClientTool> = any> {
+    /**
+     * Current messages in the conversation (reactive getter)
+     */
+    readonly messages: Array<UIMessage<TTools>>;
+    /**
+     * Send a message and get a response
+     */
+    sendMessage: (content: string) => Promise<void>;
+    /**
+     * Append a message to the conversation
+     */
+    append: (message: ModelMessage | UIMessage<TTools>) => Promise<void>;
+    /**
+     * Add the result of a client-side tool execution
+     */
+    addToolResult: (result: {
+        toolCallId: string;
+        tool: string;
+        output: any;
+        state?: 'output-available' | 'output-error';
+        errorText?: string;
+    }) => Promise<void>;
+    /**
+     * Respond to a tool approval request
+     */
+    addToolApprovalResponse: (response: {
+        id: string;
+        approved: boolean;
+    }) => Promise<void>;
+    /**
+     * Reload the last assistant message
+     */
+    reload: () => Promise<void>;
+    /**
+     * Stop the current response generation
+     */
+    stop: () => void;
+    /**
+     * Whether a response is currently being generated (reactive getter)
+     */
+    readonly isLoading: boolean;
+    /**
+     * Current error, if any (reactive getter)
+     */
+    readonly error: Error | undefined;
+    /**
+     * Set messages manually
+     */
+    setMessages: (messages: Array<UIMessage<TTools>>) => void;
+    /**
+     * Clear all messages
+     */
+    clear: () => void;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+export {};
+// Note: createChatClientOptions and InferChatMessages are now in @tanstack/ai-client
+// and re-exported from there for convenience

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@tanstack/ai-svelte",
+  "version": "0.1.1",
+  "description": "Svelte bindings for TanStack AI",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/typescript/ai-svelte"
+  },
+  "type": "module",
+  "svelte": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "ai",
+    "svelte",
+    "hooks",
+    "tanstack",
+    "chat",
+    "streaming"
+  ],
+  "dependencies": {
+    "svelte": "^5.20.0",
+    "@tanstack/ai": "0.0.3",
+    "@tanstack/ai-client": "0.0.3"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^2.3.10",
+    "@sveltejs/vite-plugin-svelte": "^5.1.1",
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "4.0.14",
+    "jsdom": "^27.2.0",
+    "svelte": "^5.20.0",
+    "svelte-check": "^4.2.0",
+    "typescript": "5.9.3",
+    "vite": "^7.2.4",
+    "zod": "^4.1.13"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0",
+    "@tanstack/ai": "0.0.3",
+    "@tanstack/ai-client": "0.0.3"
+  },
+  "scripts": {
+    "clean": "rm -rf ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest run",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "svelte-check",
+    "test:build": "publint --strict",
+    "build": "svelte-package -i src -o dist"
+  }
+}

package/src/create-chat.svelte.ts

@@ -0,0 +1,134 @@
+import { ChatClient } from '@tanstack/ai-client'
+import type { AnyClientTool, ModelMessage } from '@tanstack/ai'
+import type { CreateChatOptions, CreateChatReturn, UIMessage } from './types'
+
+/**
+ * Creates a reactive chat instance for Svelte 5.
+ *
+ * This function wraps the ChatClient from @tanstack/ai-client and exposes
+ * reactive state using Svelte 5 runes. The returned object has reactive
+ * getters that automatically update when state changes.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createChat, fetchServerSentEvents } from '@tanstack/ai-svelte'
+ *
+ *   const chat = createChat({
+ *     connection: fetchServerSentEvents('/api/chat'),
+ *   })
+ * </script>
+ *
+ * <div>
+ *   {#each chat.messages as message}
+ *     <div>{message.role}: {message.parts[0].content}</div>
+ *   {/each}
+ *
+ *   {#if chat.isLoading}
+ *     <button onclick={chat.stop}>Stop</button>
+ *   {/if}
+ *
+ *   <button onclick={() => chat.sendMessage('Hello!')}>Send</button>
+ * </div>
+ * ```
+ */
+export function createChat<TTools extends ReadonlyArray<AnyClientTool> = any>(
+  options: CreateChatOptions<TTools>,
+): CreateChatReturn<TTools> {
+  // Generate a unique ID for this chat instance
+  const clientId =
+    options.id ||
+    `chat-${Date.now()}-${Math.random().toString(36).substring(7)}`
+
+  // Create reactive state using Svelte 5 runes
+  let messages = $state<Array<UIMessage<TTools>>>(options.initialMessages || [])
+  let isLoading = $state(false)
+  let error = $state<Error | undefined>(undefined)
+
+  // Create ChatClient instance
+  const client = new ChatClient({
+    connection: options.connection,
+    id: clientId,
+    initialMessages: options.initialMessages,
+    body: options.body,
+    onResponse: options.onResponse,
+    onChunk: options.onChunk,
+    onFinish: options.onFinish,
+    onError: options.onError,
+    tools: options.tools,
+    streamProcessor: options.streamProcessor,
+    onMessagesChange: (newMessages: Array<UIMessage<TTools>>) => {
+      messages = newMessages
+    },
+    onLoadingChange: (newIsLoading: boolean) => {
+      isLoading = newIsLoading
+    },
+    onErrorChange: (newError: Error | undefined) => {
+      error = newError
+    },
+  })
+
+  // Define methods
+  const sendMessage = async (content: string) => {
+    await client.sendMessage(content)
+  }
+
+  const append = async (message: ModelMessage | UIMessage<TTools>) => {
+    await client.append(message)
+  }
+
+  const reload = async () => {
+    await client.reload()
+  }
+
+  const stop = () => {
+    client.stop()
+  }
+
+  const clear = () => {
+    client.clear()
+  }
+
+  const setMessages = (newMessages: Array<UIMessage<TTools>>) => {
+    client.setMessagesManually(newMessages)
+  }
+
+  const addToolResult = async (result: {
+    toolCallId: string
+    tool: string
+    output: any
+    state?: 'output-available' | 'output-error'
+    errorText?: string
+  }) => {
+    await client.addToolResult(result)
+  }
+
+  const addToolApprovalResponse = async (response: {
+    id: string
+    approved: boolean
+  }) => {
+    await client.addToolApprovalResponse(response)
+  }
+
+  // Return the chat interface with reactive getters
+  // Using getters allows Svelte to track reactivity without needing $ prefix
+  return {
+    get messages() {
+      return messages
+    },
+    get isLoading() {
+      return isLoading
+    },
+    get error() {
+      return error
+    },
+    sendMessage,
+    append,
+    reload,
+    stop,
+    setMessages,
+    clear,
+    addToolResult,
+    addToolApprovalResponse,
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export { createChat } from './create-chat.svelte'
+export type {
+  CreateChatOptions,
+  CreateChatReturn,
+  UIMessage,
+  ChatRequestBody,
+} from './types'
+
+// Re-export from ai-client for convenience
+export {
+  fetchServerSentEvents,
+  fetchHttpStream,
+  stream,
+  createChatClientOptions,
+  clientTools,
+  type ConnectionAdapter,
+  type FetchConnectionOptions,
+  type InferChatMessages,
+} from '@tanstack/ai-client'

package/src/types.ts

@@ -0,0 +1,102 @@
+import type { AnyClientTool, ModelMessage } from '@tanstack/ai'
+import type {
+  ChatClientOptions,
+  ChatRequestBody,
+  UIMessage,
+} from '@tanstack/ai-client'
+
+// Re-export types from ai-client
+export type { UIMessage, ChatRequestBody }
+
+/**
+ * Options for the createChat function.
+ *
+ * This extends ChatClientOptions but omits the state change callbacks that are
+ * managed internally by Svelte state:
+ * - `onMessagesChange` - Managed by Svelte state (exposed as `messages`)
+ * - `onLoadingChange` - Managed by Svelte state (exposed as `isLoading`)
+ * - `onErrorChange` - Managed by Svelte state (exposed as `error`)
+ *
+ * All other callbacks (onResponse, onChunk, onFinish, onError) are
+ * passed through to the underlying ChatClient and can be used for side effects.
+ *
+ * Note: Connection and body changes will recreate the ChatClient instance.
+ * To update these options, remount the component or use a key prop.
+ */
+export type CreateChatOptions<
+  TTools extends ReadonlyArray<AnyClientTool> = any,
+> = Omit<
+  ChatClientOptions<TTools>,
+  'onMessagesChange' | 'onLoadingChange' | 'onErrorChange'
+>
+
+export interface CreateChatReturn<
+  TTools extends ReadonlyArray<AnyClientTool> = any,
+> {
+  /**
+   * Current messages in the conversation (reactive getter)
+   */
+  readonly messages: Array<UIMessage<TTools>>
+
+  /**
+   * Send a message and get a response
+   */
+  sendMessage: (content: string) => Promise<void>
+
+  /**
+   * Append a message to the conversation
+   */
+  append: (message: ModelMessage | UIMessage<TTools>) => Promise<void>
+
+  /**
+   * Add the result of a client-side tool execution
+   */
+  addToolResult: (result: {
+    toolCallId: string
+    tool: string
+    output: any
+    state?: 'output-available' | 'output-error'
+    errorText?: string
+  }) => Promise<void>
+
+  /**
+   * Respond to a tool approval request
+   */
+  addToolApprovalResponse: (response: {
+    id: string // approval.id, not toolCallId
+    approved: boolean
+  }) => Promise<void>
+
+  /**
+   * Reload the last assistant message
+   */
+  reload: () => Promise<void>
+
+  /**
+   * Stop the current response generation
+   */
+  stop: () => void
+
+  /**
+   * Whether a response is currently being generated (reactive getter)
+   */
+  readonly isLoading: boolean
+
+  /**
+   * Current error, if any (reactive getter)
+   */
+  readonly error: Error | undefined
+
+  /**
+   * Set messages manually
+   */
+  setMessages: (messages: Array<UIMessage<TTools>>) => void
+
+  /**
+   * Clear all messages
+   */
+  clear: () => void
+}
+
+// Note: createChatClientOptions and InferChatMessages are now in @tanstack/ai-client
+// and re-exported from there for convenience