@tanstack/ai-client 0.0.1

package/src/connection-adapters.ts

@@ -0,0 +1,344 @@
+import { convertMessagesToModelMessages } from '@tanstack/ai'
+import type { ModelMessage, StreamChunk, UIMessage } from '@tanstack/ai'
+
+/**
+ * Merge custom headers into request headers
+ */
+function mergeHeaders(
+  customHeaders?: Record<string, string> | Headers,
+): Record<string, string> {
+  if (!customHeaders) {
+    return {}
+  }
+  if (customHeaders instanceof Headers) {
+    const result: Record<string, string> = {}
+    customHeaders.forEach((value, key) => {
+      result[key] = value
+    })
+    return result
+  }
+  return customHeaders
+}
+
+/**
+ * Read lines from a stream (newline-delimited)
+ */
+async function* readStreamLines(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  abortSignal?: AbortSignal,
+): AsyncGenerator<string> {
+  try {
+    const decoder = new TextDecoder()
+    let buffer = ''
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    while (true) {
+      // Check if aborted before reading
+      if (abortSignal?.aborted) {
+        break
+      }
+
+      const { done, value } = await reader.read()
+      if (done) break
+
+      buffer += decoder.decode(value, { stream: true })
+      const lines = buffer.split('\n')
+
+      // Keep the last incomplete line in the buffer
+      buffer = lines.pop() || ''
+
+      for (const line of lines) {
+        if (line.trim()) {
+          yield line
+        }
+      }
+    }
+
+    // Process any remaining data in the buffer
+    if (buffer.trim()) {
+      yield buffer
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+/**
+ * Connection adapter interface - converts a connection into a stream of chunks
+ */
+export interface ConnectionAdapter {
+  /**
+   * Connect and return an async iterable of StreamChunks
+   * @param messages - The messages to send (UIMessages or ModelMessages)
+   * @param data - Additional data to send
+   * @param abortSignal - Optional abort signal for request cancellation
+   */
+  connect: (
+    messages: Array<UIMessage> | Array<ModelMessage>,
+    data?: Record<string, any>,
+    abortSignal?: AbortSignal,
+  ) => AsyncIterable<StreamChunk>
+}
+
+/**
+ * Options for fetch-based connection adapters
+ */
+export interface FetchConnectionOptions {
+  headers?: Record<string, string> | Headers
+  credentials?: RequestCredentials
+  signal?: AbortSignal
+  body?: Record<string, any>
+}
+
+/**
+ * Create a Server-Sent Events connection adapter
+ *
+ * @param url - The API endpoint URL (or a function that returns the URL)
+ * @param options - Fetch options (headers, credentials, body, etc.) or a function that returns options (can be async)
+ * @returns A connection adapter for SSE streams
+ *
+ * @example
+ * ```typescript
+ * // Static URL
+ * const connection = fetchServerSentEvents('/api/chat');
+ *
+ * // Dynamic URL
+ * const connection = fetchServerSentEvents(() => `/api/chat?user=${userId}`);
+ *
+ * // With options
+ * const connection = fetchServerSentEvents('/api/chat', {
+ *   headers: { 'Authorization': 'Bearer token' }
+ * });
+ *
+ * // With dynamic options
+ * const connection = fetchServerSentEvents('/api/chat', () => ({
+ *   headers: { 'Authorization': `Bearer ${getToken()}` }
+ * }));
+ *
+ * // With additional body data
+ * const connection = fetchServerSentEvents('/api/chat', async () => ({
+ *   body: {
+ *     provider: 'openai',
+ *     model: 'gpt-4o',
+ *   }
+ * }));
+ * ```
+ */
+export function fetchServerSentEvents(
+  url: string | (() => string),
+  options:
+    | FetchConnectionOptions
+    | (() => FetchConnectionOptions | Promise<FetchConnectionOptions>) = {},
+): ConnectionAdapter {
+  return {
+    async *connect(messages, data, abortSignal) {
+      // Resolve URL and options if they are functions
+      const resolvedUrl = typeof url === 'function' ? url() : url
+      const resolvedOptions =
+        typeof options === 'function' ? await options() : options
+
+      const modelMessages = convertMessagesToModelMessages(messages)
+
+      const requestHeaders: Record<string, string> = {
+        'Content-Type': 'application/json',
+        ...mergeHeaders(resolvedOptions.headers),
+      }
+
+      // Merge body from options with messages and data
+      const requestBody = {
+        messages: modelMessages,
+        data,
+        ...resolvedOptions.body,
+      }
+
+      const response = await fetch(resolvedUrl, {
+        method: 'POST',
+        headers: requestHeaders,
+        body: JSON.stringify(requestBody),
+        credentials: resolvedOptions.credentials || 'same-origin',
+        signal: abortSignal || resolvedOptions.signal,
+      })
+
+      if (!response.ok) {
+        throw new Error(
+          `HTTP error! status: ${response.status} ${response.statusText}`,
+        )
+      }
+
+      // Parse Server-Sent Events format
+      const reader = response.body?.getReader()
+      if (!reader) {
+        throw new Error('Response body is not readable')
+      }
+
+      for await (const line of readStreamLines(reader, abortSignal)) {
+        // Handle Server-Sent Events format
+        const data = line.startsWith('data: ') ? line.slice(6) : line
+
+        if (data === '[DONE]') continue
+
+        try {
+          const parsed: StreamChunk = JSON.parse(data)
+          yield parsed
+        } catch (parseError) {
+          // Skip non-JSON lines or malformed chunks
+          console.warn('Failed to parse SSE chunk:', data)
+        }
+      }
+    },
+  }
+}
+
+/**
+ * Create an HTTP streaming connection adapter (for raw streaming without SSE format)
+ *
+ * @param url - The API endpoint URL (or a function that returns the URL)
+ * @param options - Fetch options (headers, credentials, body, etc.) or a function that returns options (can be async)
+ * @returns A connection adapter for HTTP streams
+ *
+ * @example
+ * ```typescript
+ * // Static URL
+ * const connection = fetchHttpStream('/api/chat');
+ *
+ * // Dynamic URL
+ * const connection = fetchHttpStream(() => `/api/chat?user=${userId}`);
+ *
+ * // With options
+ * const connection = fetchHttpStream('/api/chat', {
+ *   headers: { 'Authorization': 'Bearer token' }
+ * });
+ *
+ * // With dynamic options
+ * const connection = fetchHttpStream('/api/chat', () => ({
+ *   headers: { 'Authorization': `Bearer ${getToken()}` }
+ * }));
+ *
+ * // With additional body data
+ * const connection = fetchHttpStream('/api/chat', async () => ({
+ *   body: {
+ *     provider: 'openai',
+ *     model: 'gpt-4o',
+ *   }
+ * }));
+ * ```
+ */
+export function fetchHttpStream(
+  url: string | (() => string),
+  options:
+    | FetchConnectionOptions
+    | (() => FetchConnectionOptions | Promise<FetchConnectionOptions>) = {},
+): ConnectionAdapter {
+  return {
+    async *connect(messages, data, abortSignal) {
+      // Resolve URL and options if they are functions
+      const resolvedUrl = typeof url === 'function' ? url() : url
+      const resolvedOptions =
+        typeof options === 'function' ? await options() : options
+
+      // Convert UIMessages to ModelMessages if needed
+      const modelMessages = convertMessagesToModelMessages(messages)
+
+      const requestHeaders: Record<string, string> = {
+        'Content-Type': 'application/json',
+        ...mergeHeaders(resolvedOptions.headers),
+      }
+
+      // Merge body from options with messages and data
+      const requestBody = {
+        messages: modelMessages,
+        data,
+        ...resolvedOptions.body,
+      }
+
+      const response = await fetch(resolvedUrl, {
+        method: 'POST',
+        headers: requestHeaders,
+        body: JSON.stringify(requestBody),
+        credentials: resolvedOptions.credentials || 'same-origin',
+        signal: abortSignal || resolvedOptions.signal,
+      })
+
+      if (!response.ok) {
+        throw new Error(
+          `HTTP error! status: ${response.status} ${response.statusText}`,
+        )
+      }
+
+      // Parse raw HTTP stream (newline-delimited JSON)
+      const reader = response.body?.getReader()
+      if (!reader) {
+        throw new Error('Response body is not readable')
+      }
+
+      for await (const line of readStreamLines(reader, abortSignal)) {
+        try {
+          const parsed: StreamChunk = JSON.parse(line)
+          yield parsed
+        } catch (parseError) {
+          console.warn('Failed to parse HTTP stream chunk:', line)
+        }
+      }
+    },
+  }
+}
+
+/**
+ * Create a direct stream connection adapter (for server functions or direct streams)
+ *
+ * @param streamFactory - A function that returns an async iterable of StreamChunks
+ * @returns A connection adapter for direct streams
+ *
+ * @example
+ * ```typescript
+ * // With TanStack Start server function
+ * const connection = stream(() => serverFunction({ messages }));
+ *
+ * const client = new ChatClient({ connection });
+ * ```
+ */
+export function stream(
+  streamFactory: (
+    messages: Array<ModelMessage>,
+    data?: Record<string, any>,
+  ) => AsyncIterable<StreamChunk>,
+): ConnectionAdapter {
+  return {
+    async *connect(messages, data) {
+      const modelMessages = convertMessagesToModelMessages(messages)
+      yield* streamFactory(modelMessages, data)
+    },
+  }
+}
+
+/**
+ * Create an RPC stream connection adapter (for RPC-based streaming like Cap'n Web RPC)
+ *
+ * @param rpcCall - A function that accepts messages and returns an async iterable of StreamChunks
+ * @returns A connection adapter for RPC streams
+ *
+ * @example
+ * ```typescript
+ * // With Cap'n Web RPC
+ * const connection = rpcStream((messages, data) =>
+ *   api.streamMurfResponse(messages, data)
+ * );
+ *
+ * const client = new ChatClient({ connection });
+ * ```
+ */
+export function rpcStream(
+  rpcCall: (
+    messages: Array<ModelMessage>,
+    data?: Record<string, any>,
+  ) => AsyncIterable<StreamChunk>,
+): ConnectionAdapter {
+  return {
+    async *connect(messages, data) {
+      const modelMessages = convertMessagesToModelMessages(messages)
+      // Simply yield from the RPC call
+      // The RPC layer handles WebSocket transport
+      yield* rpcCall(modelMessages, data)
+    },
+  }
+}

package/src/events.ts

@@ -0,0 +1,252 @@
+import { aiEventClient } from '@tanstack/ai/event-client'
+import type { UIMessage } from './types'
+
+/**
+ * Abstract base class for ChatClient event emission
+ */
+export abstract class ChatClientEventEmitter {
+  protected clientId: string
+
+  constructor(clientId: string) {
+    this.clientId = clientId
+  }
+
+  /**
+   * Protected abstract method for emitting events
+   * Implementations should handle adding clientId and timestamp
+   */
+  protected abstract emitEvent(
+    eventName: string,
+    data?: Record<string, any>,
+  ): void
+
+  /**
+   * Emit client created event
+   */
+  clientCreated(initialMessageCount: number): void {
+    this.emitEvent('client:created', {
+      initialMessageCount,
+    })
+  }
+
+  /**
+   * Emit loading state changed event
+   */
+  loadingChanged(isLoading: boolean): void {
+    this.emitEvent('client:loading-changed', { isLoading })
+  }
+
+  /**
+   * Emit error state changed event
+   */
+  errorChanged(error: string | null): void {
+    this.emitEvent('client:error-changed', {
+      error,
+    })
+  }
+
+  /**
+   * Emit text update events (combines processor and client events)
+   */
+  textUpdated(streamId: string, messageId: string, content: string): void {
+    this.emitEvent('processor:text-updated', {
+      streamId,
+      content,
+    })
+
+    this.emitEvent('client:assistant-message-updated', {
+      messageId,
+      content,
+    })
+  }
+
+  /**
+   * Emit tool call state change events (combines processor and client events)
+   */
+  toolCallStateChanged(
+    streamId: string,
+    messageId: string,
+    toolCallId: string,
+    toolName: string,
+    state: string,
+    args: string,
+  ): void {
+    this.emitEvent('processor:tool-call-state-changed', {
+      streamId,
+      toolCallId,
+      toolName,
+      state,
+      arguments: args,
+    })
+
+    this.emitEvent('client:tool-call-updated', {
+      messageId,
+      toolCallId,
+      toolName,
+      state,
+      arguments: args,
+    })
+  }
+
+  /**
+   * Emit tool result state change event
+   */
+  toolResultStateChanged(
+    streamId: string,
+    toolCallId: string,
+    content: string,
+    state: string,
+    error?: string,
+  ): void {
+    this.emitEvent('processor:tool-result-state-changed', {
+      streamId,
+      toolCallId,
+      content,
+      state,
+      error,
+    })
+  }
+
+  /**
+   * Emit thinking update event
+   */
+  thinkingUpdated(
+    streamId: string,
+    messageId: string,
+    content: string,
+    delta?: string,
+  ): void {
+    this.emitEvent('stream:chunk:thinking', {
+      streamId,
+      messageId,
+      content,
+      delta,
+    })
+  }
+
+  /**
+   * Emit approval requested event
+   */
+  approvalRequested(
+    messageId: string,
+    toolCallId: string,
+    toolName: string,
+    input: any,
+    approvalId: string,
+  ): void {
+    this.emitEvent('client:approval-requested', {
+      messageId,
+      toolCallId,
+      toolName,
+      input,
+      approvalId,
+    })
+  }
+
+  /**
+   * Emit message appended event
+   */
+  messageAppended(uiMessage: UIMessage): void {
+    const contentPreview = uiMessage.parts
+      .filter((p) => p.type === 'text')
+      .map((p) => (p as any).content)
+      .join(' ')
+      .substring(0, 100)
+
+    this.emitEvent('client:message-appended', {
+      messageId: uiMessage.id,
+      role: uiMessage.role,
+      contentPreview,
+    })
+  }
+
+  /**
+   * Emit message sent event
+   */
+  messageSent(messageId: string, content: string): void {
+    this.emitEvent('client:message-sent', {
+      messageId,
+      content,
+    })
+  }
+
+  /**
+   * Emit reloaded event
+   */
+  reloaded(fromMessageIndex: number): void {
+    this.emitEvent('client:reloaded', {
+      fromMessageIndex,
+    })
+  }
+
+  /**
+   * Emit stopped event
+   */
+  stopped(): void {
+    this.emitEvent('client:stopped')
+  }
+
+  /**
+   * Emit messages cleared event
+   */
+  messagesCleared(): void {
+    this.emitEvent('client:messages-cleared')
+  }
+
+  /**
+   * Emit tool result added event
+   */
+  toolResultAdded(
+    toolCallId: string,
+    toolName: string,
+    output: any,
+    state: string,
+  ): void {
+    this.emitEvent('tool:result-added', {
+      toolCallId,
+      toolName,
+      output,
+      state,
+    })
+  }
+
+  /**
+   * Emit tool approval responded event
+   */
+  toolApprovalResponded(
+    approvalId: string,
+    toolCallId: string,
+    approved: boolean,
+  ): void {
+    this.emitEvent('tool:approval-responded', {
+      approvalId,
+      toolCallId,
+      approved,
+    })
+  }
+}
+
+/**
+ * Default implementation of ChatClientEventEmitter
+ */
+export class DefaultChatClientEventEmitter extends ChatClientEventEmitter {
+  /**
+   * Emit an event with automatic clientId and timestamp for client/tool events
+   */
+  protected emitEvent(eventName: string, data?: Record<string, any>): void {
+    // For client:* and tool:* events, automatically add clientId and timestamp
+    if (eventName.startsWith('client:') || eventName.startsWith('tool:')) {
+      aiEventClient.emit(eventName as any, {
+        ...data,
+        clientId: this.clientId,
+        timestamp: Date.now(),
+      })
+    } else {
+      // For other events (e.g., processor:*), just add timestamp
+      aiEventClient.emit(eventName as any, {
+        ...data,
+        timestamp: Date.now(),
+      })
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+export { ChatClient } from './chat-client'
+export type {
+  // Core message types (re-exported from @tanstack/ai via types.ts)
+  UIMessage,
+  MessagePart,
+  TextPart,
+  ToolCallPart,
+  ToolResultPart,
+  ThinkingPart,
+  // Client configuration types
+  ChatClientOptions,
+  ChatRequestBody,
+  InferChatMessages,
+} from './types'
+export { clientTools, createChatClientOptions } from './types'
+export type {
+  ExtractToolNames,
+  ExtractToolInput,
+  ExtractToolOutput,
+} from './tool-types'
+export type { AnyClientTool } from '@tanstack/ai'
+export {
+  fetchServerSentEvents,
+  fetchHttpStream,
+  stream,
+  rpcStream,
+  type ConnectionAdapter,
+  type FetchConnectionOptions,
+} from './connection-adapters'
+
+// Re-export message converters from @tanstack/ai
+export {
+  uiMessageToModelMessages,
+  modelMessageToUIMessage,
+  modelMessagesToUIMessages,
+  convertMessagesToModelMessages,
+  normalizeToUIMessage,
+  generateMessageId,
+} from '@tanstack/ai'
+
+// Re-export stream processing from @tanstack/ai (shared implementation)
+export {
+  StreamProcessor,
+  ImmediateStrategy,
+  PunctuationStrategy,
+  BatchStrategy,
+  WordBoundaryStrategy,
+  CompositeStrategy,
+  parsePartialJSON,
+  PartialJSONParser,
+  defaultJSONParser,
+  type ChunkStrategy,
+  type StreamProcessorOptions,
+  type StreamProcessorHandlers,
+  type StreamProcessorEvents,
+  type InternalToolCallState,
+  type ToolCallState,
+  type ToolResultState,
+  type JSONParser,
+  type ChunkRecording,
+  type ProcessorResult,
+  type ProcessorState,
+} from '@tanstack/ai'

package/src/tool-types.ts

@@ -0,0 +1,41 @@
+import type {
+  AnyClientTool,
+  InferToolInput,
+  InferToolOutput,
+} from '@tanstack/ai'
+
+/**
+ * Extract all tool names from a tools array as a union type
+ */
+export type ExtractToolNames<TTools extends ReadonlyArray<AnyClientTool>> =
+  TTools[number]['name']
+
+/**
+ * Find a tool by name in the tools array
+ */
+type FindTool<
+  TTools extends ReadonlyArray<AnyClientTool>,
+  TName extends string,
+> = Extract<TTools[number], { name: TName }>
+
+/**
+ * Extract the input type for a specific tool by name
+ */
+export type ExtractToolInput<
+  TTools extends ReadonlyArray<AnyClientTool>,
+  TName extends string,
+> =
+  TName extends ExtractToolNames<TTools>
+    ? InferToolInput<FindTool<TTools, TName>>
+    : any
+
+/**
+ * Extract the output type for a specific tool by name
+ */
+export type ExtractToolOutput<
+  TTools extends ReadonlyArray<AnyClientTool>,
+  TName extends string,
+> =
+  TName extends ExtractToolNames<TTools>
+    ? InferToolOutput<FindTool<TTools, TName>>
+    : any