@tanstack/ai-client 0.0.1

package/dist/esm/types.d.ts

@@ -0,0 +1,210 @@
+import { AnyClientTool, ChunkStrategy, InferToolInput, InferToolOutput, ModelMessage, StreamChunk } from '@tanstack/ai';
+import { ConnectionAdapter } from './connection-adapters.js';
+/**
+ * Tool call states - track the lifecycle of a tool call
+ */
+export type ToolCallState = 'awaiting-input' | 'input-streaming' | 'input-complete' | 'approval-requested' | 'approval-responded';
+/**
+ * Tool result states - track the lifecycle of a tool result
+ */
+export type ToolResultState = 'streaming' | 'complete' | 'error';
+/**
+ * Message parts - building blocks of UIMessage
+ */
+export interface TextPart {
+    type: 'text';
+    content: string;
+}
+/**
+ * Helper type that creates a tool-call part for a specific tool.
+ * This is a conditional type to enable proper distribution over union types,
+ * creating a discriminated union where `name` is the discriminant.
+ */
+type ToolCallPartForTool<T> = T extends AnyClientTool ? {
+    type: 'tool-call';
+    id: string;
+    name: T['name'];
+    arguments: string;
+    /** Parsed tool input (typed from inputSchema) */
+    input?: InferToolInput<T>;
+    state: ToolCallState;
+    /** Approval metadata if tool requires user approval */
+    approval?: {
+        id: string;
+        needsApproval: boolean;
+        approved?: boolean;
+    };
+    /** Tool execution output (for client tools or after approval) */
+    output?: InferToolOutput<T>;
+} : never;
+/**
+ * Fallback tool-call part type when tools are not typed
+ */
+type UntypedToolCallPart = {
+    type: 'tool-call';
+    id: string;
+    name: string;
+    arguments: string;
+    input?: any;
+    state: ToolCallState;
+    approval?: {
+        id: string;
+        needsApproval: boolean;
+        approved?: boolean;
+    };
+    output?: any;
+};
+/**
+ * Tool call part that creates a proper discriminated union.
+ * When TTools is typed, checking `part.name === 'toolName'` will narrow
+ * `part.output` to the correct type for that tool.
+ *
+ * The discriminant is `name`, so code like:
+ * ```ts
+ * if (part.name === 'recommendGuitar') {
+ *   // part.output is now typed to the recommendGuitar tool's output
+ * }
+ * ```
+ */
+export type ToolCallPart<TTools extends ReadonlyArray<AnyClientTool> = any> = [
+    TTools
+] extends [never] ? UntypedToolCallPart : unknown extends TTools ? UntypedToolCallPart : TTools extends ReadonlyArray<infer Tool> ? Tool extends AnyClientTool ? ToolCallPartForTool<Tool> : UntypedToolCallPart : UntypedToolCallPart;
+export interface ToolResultPart {
+    type: 'tool-result';
+    toolCallId: string;
+    content: string;
+    state: ToolResultState;
+    error?: string;
+}
+export interface ThinkingPart {
+    type: 'thinking';
+    content: string;
+}
+export type MessagePart<TTools extends ReadonlyArray<AnyClientTool> = any> = TextPart | ToolCallPart<TTools> | ToolResultPart | ThinkingPart;
+/**
+ * UIMessage - Domain-specific message format optimized for building chat UIs
+ * Contains parts that can be text, tool calls, or tool results
+ */
+export interface UIMessage<TTools extends ReadonlyArray<AnyClientTool> = any> {
+    id: string;
+    role: 'user' | 'assistant';
+    parts: Array<MessagePart<TTools>>;
+    createdAt?: Date;
+}
+export interface ChatClientOptions<TTools extends ReadonlyArray<AnyClientTool> = any> {
+    /**
+     * Connection adapter for streaming
+     * Use fetchServerSentEvents(), fetchHttpStream(), or stream() to create adapters
+     */
+    connection: ConnectionAdapter;
+    /**
+     * Initial messages to populate the chat
+     */
+    initialMessages?: Array<UIMessage<TTools>>;
+    /**
+     * Unique identifier for this chat instance
+     * Used for managing multiple chats
+     */
+    id?: string;
+    /**
+     * Additional body parameters to send
+     */
+    body?: Record<string, any>;
+    /**
+     * Callback when a response is received
+     */
+    onResponse?: (response?: Response) => void | Promise<void>;
+    /**
+     * Callback when a stream chunk is received
+     */
+    onChunk?: (chunk: StreamChunk) => void;
+    /**
+     * Callback when the response is finished
+     */
+    onFinish?: (message: UIMessage<TTools>) => void;
+    /**
+     * Callback when an error occurs
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Callback when messages change
+     */
+    onMessagesChange?: (messages: Array<UIMessage<TTools>>) => void;
+    /**
+     * Callback when loading state changes
+     */
+    onLoadingChange?: (isLoading: boolean) => void;
+    /**
+     * Callback when error state changes
+     */
+    onErrorChange?: (error: Error | undefined) => void;
+    /**
+     * Client-side tools with execution logic
+     * When provided, tools with execute functions will be called automatically
+     */
+    tools?: TTools;
+    /**
+     * Stream processing options (optional)
+     * Configure chunking strategy
+     */
+    streamProcessor?: {
+        /**
+         * Strategy for when to emit text updates
+         * Defaults to ImmediateStrategy (every chunk)
+         */
+        chunkStrategy?: ChunkStrategy;
+    };
+}
+export interface ChatRequestBody {
+    messages: Array<ModelMessage>;
+    data?: Record<string, any>;
+}
+/**
+ * Create a typed array of client tools with proper type inference.
+ * This eliminates the need for `as const` when defining tool arrays.
+ *
+ * @example
+ * ```ts
+ * const tools = clientTools(
+ *   myTool1.client(() => result1),
+ *   myTool2.client(() => result2),
+ * )
+ *
+ * // tools is now properly typed as a tuple with literal tool names
+ * // This enables type narrowing when checking part.name === 'toolName'
+ * ```
+ */
+export declare function clientTools<const T extends Array<AnyClientTool>>(...tools: T): T;
+/**
+ * Helper to create typed chat client options
+ * Use this to get proper type inference for messages
+ *
+ * @example
+ * ```ts
+ * const tools = clientTools(myTool1, myTool2)
+ *
+ * const chatOptions = createChatClientOptions({
+ *   connection: fetchServerSentEvents('/api/chat'),
+ *   tools,
+ * })
+ *
+ * type MyMessages = InferChatMessages<typeof chatOptions>
+ * ```
+ */
+export declare function createChatClientOptions<const TTools extends ReadonlyArray<AnyClientTool>>(options: ChatClientOptions<TTools>): ChatClientOptions<TTools>;
+/**
+ * Extract the message type from chat options
+ *
+ * @example
+ * ```ts
+ * const chatOptions = createChatClientOptions({
+ *   connection: fetchServerSentEvents('/api/chat'),
+ *   tools: [myTool1, myTool2],
+ * })
+ *
+ * type MyMessages = InferChatMessages<typeof chatOptions>
+ * // MyMessages is now Array<UIMessage<[typeof myTool1, typeof myTool2]>>
+ * ```
+ */
+export type InferChatMessages<T> = T extends ChatClientOptions<infer TTools> ? Array<UIMessage<TTools>> : never;
+export {};

package/dist/esm/types.js

@@ -0,0 +1,11 @@
+function clientTools(...tools) {
+  return tools;
+}
+function createChatClientOptions(options) {
+  return options;
+}
+export {
+  clientTools,
+  createChatClientOptions
+};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sources":["../../src/types.ts"],"sourcesContent":["import type {\n  AnyClientTool,\n  ChunkStrategy,\n  InferToolInput,\n  InferToolOutput,\n  ModelMessage,\n  StreamChunk,\n} from '@tanstack/ai'\nimport type { ConnectionAdapter } from './connection-adapters'\n\n/**\n * Tool call states - track the lifecycle of a tool call\n */\nexport type ToolCallState =\n  | 'awaiting-input' // Received start but no arguments yet\n  | 'input-streaming' // Partial arguments received\n  | 'input-complete' // All arguments received\n  | 'approval-requested' // Waiting for user approval\n  | 'approval-responded' // User has approved/denied\n\n/**\n * Tool result states - track the lifecycle of a tool result\n */\nexport type ToolResultState =\n  | 'streaming' // Placeholder for future streamed output\n  | 'complete' // Result is complete\n  | 'error' // Error occurred\n\n/**\n * Message parts - building blocks of UIMessage\n */\nexport interface TextPart {\n  type: 'text'\n  content: string\n}\n\n/**\n * Helper type that creates a tool-call part for a specific tool.\n * This is a conditional type to enable proper distribution over union types,\n * creating a discriminated union where `name` is the discriminant.\n */\ntype ToolCallPartForTool<T> = T extends AnyClientTool\n  ? {\n      type: 'tool-call'\n      id: string\n      name: T['name']\n      arguments: string // JSON string (may be incomplete)\n      /** Parsed tool input (typed from inputSchema) */\n      input?: InferToolInput<T>\n      state: ToolCallState\n      /** Approval metadata if tool requires user approval */\n      approval?: {\n        id: string // Unique approval ID\n        needsApproval: boolean // Always true if present\n        approved?: boolean // User's decision (undefined until responded)\n      }\n      /** Tool execution output (for client tools or after approval) */\n      output?: InferToolOutput<T>\n    }\n  : never\n\n/**\n * Fallback tool-call part type when tools are not typed\n */\ntype UntypedToolCallPart = {\n  type: 'tool-call'\n  id: string\n  name: string\n  arguments: string\n  input?: any\n  state: ToolCallState\n  approval?: {\n    id: string\n    needsApproval: boolean\n    approved?: boolean\n  }\n  output?: any\n}\n\n/**\n * Tool call part that creates a proper discriminated union.\n * When TTools is typed, checking `part.name === 'toolName'` will narrow\n * `part.output` to the correct type for that tool.\n *\n * The discriminant is `name`, so code like:\n * ```ts\n * if (part.name === 'recommendGuitar') {\n *   // part.output is now typed to the recommendGuitar tool's output\n * }\n * ```\n */\nexport type ToolCallPart<TTools extends ReadonlyArray<AnyClientTool> = any> =\n  // Check if we have a concrete tools array (not 'any' or 'never')\n  [TTools] extends [never]\n    ? UntypedToolCallPart\n    : unknown extends TTools\n      ? UntypedToolCallPart\n      : TTools extends ReadonlyArray<infer Tool>\n        ? Tool extends AnyClientTool\n          ? ToolCallPartForTool<Tool>\n          : UntypedToolCallPart\n        : UntypedToolCallPart\n\nexport interface ToolResultPart {\n  type: 'tool-result'\n  toolCallId: string\n  content: string\n  state: ToolResultState\n  error?: string // Error message if state is \"error\"\n}\n\nexport interface ThinkingPart {\n  type: 'thinking'\n  content: string\n}\n\nexport type MessagePart<TTools extends ReadonlyArray<AnyClientTool> = any> =\n  | TextPart\n  | ToolCallPart<TTools>\n  | ToolResultPart\n  | ThinkingPart\n\n/**\n * UIMessage - Domain-specific message format optimized for building chat UIs\n * Contains parts that can be text, tool calls, or tool results\n */\nexport interface UIMessage<TTools extends ReadonlyArray<AnyClientTool> = any> {\n  id: string\n  role: 'user' | 'assistant'\n  parts: Array<MessagePart<TTools>>\n  createdAt?: Date\n}\n\nexport interface ChatClientOptions<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n> {\n  /**\n   * Connection adapter for streaming\n   * Use fetchServerSentEvents(), fetchHttpStream(), or stream() to create adapters\n   */\n  connection: ConnectionAdapter\n\n  /**\n   * Initial messages to populate the chat\n   */\n  initialMessages?: Array<UIMessage<TTools>>\n\n  /**\n   * Unique identifier for this chat instance\n   * Used for managing multiple chats\n   */\n  id?: string\n\n  /**\n   * Additional body parameters to send\n   */\n  body?: Record<string, any>\n\n  /**\n   * Callback when a response is received\n   */\n  onResponse?: (response?: Response) => void | Promise<void>\n\n  /**\n   * Callback when a stream chunk is received\n   */\n  onChunk?: (chunk: StreamChunk) => void\n\n  /**\n   * Callback when the response is finished\n   */\n  onFinish?: (message: UIMessage<TTools>) => void\n\n  /**\n   * Callback when an error occurs\n   */\n  onError?: (error: Error) => void\n\n  /**\n   * Callback when messages change\n   */\n  onMessagesChange?: (messages: Array<UIMessage<TTools>>) => void\n\n  /**\n   * Callback when loading state changes\n   */\n  onLoadingChange?: (isLoading: boolean) => void\n\n  /**\n   * Callback when error state changes\n   */\n  onErrorChange?: (error: Error | undefined) => void\n\n  /**\n   * Client-side tools with execution logic\n   * When provided, tools with execute functions will be called automatically\n   */\n  tools?: TTools\n\n  /**\n   * Stream processing options (optional)\n   * Configure chunking strategy\n   */\n  streamProcessor?: {\n    /**\n     * Strategy for when to emit text updates\n     * Defaults to ImmediateStrategy (every chunk)\n     */\n    chunkStrategy?: ChunkStrategy\n  }\n}\n\nexport interface ChatRequestBody {\n  messages: Array<ModelMessage>\n  data?: Record<string, any>\n}\n\n/**\n * Create a typed array of client tools with proper type inference.\n * This eliminates the need for `as const` when defining tool arrays.\n *\n * @example\n * ```ts\n * const tools = clientTools(\n *   myTool1.client(() => result1),\n *   myTool2.client(() => result2),\n * )\n *\n * // tools is now properly typed as a tuple with literal tool names\n * // This enables type narrowing when checking part.name === 'toolName'\n * ```\n */\nexport function clientTools<const T extends Array<AnyClientTool>>(\n  ...tools: T\n): T {\n  return tools\n}\n\n/**\n * Helper to create typed chat client options\n * Use this to get proper type inference for messages\n *\n * @example\n * ```ts\n * const tools = clientTools(myTool1, myTool2)\n *\n * const chatOptions = createChatClientOptions({\n *   connection: fetchServerSentEvents('/api/chat'),\n *   tools,\n * })\n *\n * type MyMessages = InferChatMessages<typeof chatOptions>\n * ```\n */\nexport function createChatClientOptions<\n  const TTools extends ReadonlyArray<AnyClientTool>,\n>(options: ChatClientOptions<TTools>): ChatClientOptions<TTools> {\n  return options\n}\n\n/**\n * Extract the message type from chat options\n *\n * @example\n * ```ts\n * const chatOptions = createChatClientOptions({\n *   connection: fetchServerSentEvents('/api/chat'),\n *   tools: [myTool1, myTool2],\n * })\n *\n * type MyMessages = InferChatMessages<typeof chatOptions>\n * // MyMessages is now Array<UIMessage<[typeof myTool1, typeof myTool2]>>\n * ```\n */\nexport type InferChatMessages<T> =\n  T extends ChatClientOptions<infer TTools> ? Array<UIMessage<TTools>> : never\n"],"names":[],"mappings":"AAwOO,SAAS,eACX,OACA;AACH,SAAO;AACT;AAkBO,SAAS,wBAEd,SAA+D;AAC/D,SAAO;AACT;"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@tanstack/ai-client",
+  "version": "0.0.1",
+  "description": "Framework-agnostic headless client for TanStack AI",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/typescript/ai-client"
+  },
+  "keywords": [
+    "ai",
+    "client",
+    "headless",
+    "tanstack",
+    "chat",
+    "streaming"
+  ],
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@tanstack/ai": "0.0.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.0.14",
+    "vite": "^7.2.4",
+    "zod": "^4.1.13"
+  },
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:watch": "vitest --coverage --watch",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  }
+}