@tambo-ai/client 0.0.1

package/dist/tambo-client.d.ts

@@ -0,0 +1,292 @@
+/**
+ * TamboClient - Framework-agnostic client for Tambo AI
+ *
+ * Main entry point for the `@tambo-ai/client` package. Manages threads,
+ * tool registration, streaming, and state. Compatible with
+ * useSyncExternalStore for React integration.
+ */
+import TamboAI from "@tambo-ai/typescript-sdk";
+import type { Suggestion } from "@tambo-ai/typescript-sdk/resources/beta/threads/suggestions";
+import type { TamboThread } from "./types/thread";
+import type { TamboAuthState } from "./types/auth";
+import type { ToolChoice } from "./types/tool-choice";
+import type { InputMessage } from "./types/message";
+import type { TamboTool, ComponentRegistry } from "./model/component-metadata";
+import type { McpServerInfo } from "./model/mcp-server-info";
+import { MCPClient } from "./mcp/mcp-client";
+import { type ThreadState } from "./utils/event-accumulator";
+import { TamboStream } from "./tambo-stream";
+/**
+ * Function that returns context to be merged into additionalContext before each run.
+ */
+export type ContextHelperFn = () => Record<string, unknown> | Promise<Record<string, unknown>>;
+/**
+ * Callback invoked before each run starts.
+ */
+export interface BeforeRunContext {
+    /** Thread ID (undefined for new threads). */
+    threadId: string | undefined;
+    /** The message being sent. */
+    message: InputMessage;
+    /** Frozen copy of registered tools (cannot mutate). */
+    tools: Readonly<Record<string, TamboTool>>;
+}
+/**
+ * Options for configuring TamboClient.
+ */
+export interface TamboClientOptions {
+    /** API key for authentication. */
+    apiKey: string;
+    /** Custom Tambo API URL. Conflicts with `environment`. */
+    tamboUrl?: string;
+    /** Environment preset. Conflicts with `tamboUrl`. */
+    environment?: "production" | "staging";
+    /** User key for identifying the user. */
+    userKey?: string;
+    /** User token for token-based auth. */
+    userToken?: string;
+    /** Tools to register on creation. */
+    tools?: TamboTool[];
+    /** MCP servers to connect on init. */
+    mcpServers?: McpServerInfo[];
+    /** Callback invoked before each run. */
+    beforeRun?: (context: BeforeRunContext) => void | Promise<void>;
+}
+/**
+ * Options for the `run()` method.
+ */
+export interface RunOptions {
+    /** Thread ID to run on. If omitted, creates a new thread. */
+    threadId?: string;
+    /** Whether to auto-execute tools when the model requests them. */
+    autoExecuteTools?: boolean;
+    /** Max tool execution rounds (default 10). */
+    maxSteps?: number;
+    /** How the model should select tools. */
+    toolChoice?: ToolChoice;
+    /** Enable debug logging. */
+    debug?: boolean;
+    /** Additional context merged into the message. */
+    additionalContext?: Record<string, unknown>;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+    /** User message text for optimistic display. */
+    userMessageText?: string;
+}
+/**
+ * Public client state exposed via `getState()`.
+ */
+export interface ClientState {
+    /** Map of thread ID to thread state. */
+    threadMap: Record<string, ThreadState>;
+    /** Currently active thread ID. */
+    currentThreadId: string;
+}
+/**
+ * TamboClient manages threads, tool execution, streaming, and state.
+ *
+ * Compatible with `useSyncExternalStore(client.subscribe, client.getState)`
+ * for React integration.
+ * @example
+ * ```typescript
+ * const client = new TamboClient({ apiKey: "your-api-key" });
+ *
+ * // Stream mode
+ * const stream = client.run("Hello, AI!");
+ * for await (const { event, snapshot } of stream) {
+ *   console.log(snapshot.messages);
+ * }
+ *
+ * // Promise mode
+ * const thread = await client.run("Hello, AI!").thread;
+ * console.log(thread.messages);
+ * ```
+ */
+export declare class TamboClient {
+    private sdkClient;
+    private state;
+    private listeners;
+    private pendingNotification;
+    private toolRegistry;
+    private componentList;
+    private mcpClients;
+    private activeRuns;
+    private contextHelpers;
+    private readonly options;
+    /**
+     * Create a new TamboClient.
+     * @param options - Client configuration.
+     */
+    constructor(options: TamboClientOptions);
+    /**
+     * Start a new run with a message. Returns a TamboStream immediately.
+     *
+     * The stream's processing loop runs in the background. Use async iteration
+     * to observe events, or `await stream.thread` to get the final result.
+     * @param message - The message string or InputMessage object.
+     * @param options - Run configuration.
+     * @returns A TamboStream for observing the response.
+     */
+    run(message: string | InputMessage, options?: RunOptions): TamboStream;
+    /**
+     * Switch to an existing thread. Fetches thread data from the API.
+     * @param threadId - The thread ID to switch to.
+     */
+    switchThread(threadId: string): Promise<void>;
+    /**
+     * Start a new thread. Returns the new thread ID.
+     * @returns The new placeholder thread ID.
+     */
+    startNewThread(): string;
+    /**
+     * Get a thread from local state.
+     * @param threadId - The thread ID.
+     * @returns The thread, or undefined if not found.
+     */
+    getThread(threadId: string): TamboThread | undefined;
+    /**
+     * List all threads from the API.
+     * @returns An array of TamboThread objects.
+     */
+    listThreads(): Promise<TamboThread[]>;
+    /**
+     * Fetch a thread from the API and hydrate it into local state.
+     * @param threadId - The thread ID to fetch.
+     * @returns The fetched thread.
+     */
+    fetchThread(threadId: string): Promise<TamboThread>;
+    /**
+     * Register a single tool.
+     * @param tool - The tool to register.
+     */
+    registerTool(tool: TamboTool): void;
+    /**
+     * Register multiple tools at once.
+     * @param tools - The tools to register.
+     */
+    registerTools(tools: TamboTool[]): void;
+    /**
+     * Register a component.
+     * @param name - Component name.
+     * @param component - The registered component.
+     */
+    registerComponent(name: string, component: ComponentRegistry[string]): void;
+    /**
+     * Get the current client state snapshot.
+     * @returns The current client state.
+     */
+    getState(): ClientState;
+    /**
+     * Subscribe to state changes.
+     * @param listener - Callback invoked on state change.
+     * @returns Unsubscribe function.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Compute and return the current auth state. Not stored in state;
+     * computed on each call from config.
+     * @returns The current auth state.
+     */
+    getAuthState(): TamboAuthState;
+    /**
+     * Cancel the active run on a thread.
+     * @param threadId - The thread whose run to cancel. Defaults to current thread.
+     */
+    cancelRun(threadId?: string): Promise<void>;
+    /**
+     * Update a thread's name via the API.
+     * @param threadId - The thread ID.
+     * @param name - The new name.
+     */
+    updateThreadName(threadId: string, name: string): Promise<void>;
+    /**
+     * Generate a thread name via the API.
+     * @param threadId - The thread ID.
+     * @returns The generated name.
+     */
+    generateThreadName(threadId: string): Promise<string>;
+    /**
+     * Connect to an MCP server.
+     * @param serverInfo - The MCP server configuration.
+     * @returns The connected MCPClient.
+     */
+    connectMcpServer(serverInfo: McpServerInfo): Promise<MCPClient>;
+    /**
+     * Disconnect from an MCP server.
+     * @param serverKey - The server key (from getMcpServerUniqueKey).
+     */
+    disconnectMcpServer(serverKey: string): Promise<void>;
+    /**
+     * Get all connected MCP clients.
+     * @returns Record of server key to MCPClient.
+     */
+    getMcpClients(): Record<string, MCPClient>;
+    /**
+     * Get an MCP token for a context key.
+     * @param contextKey - The context key.
+     * @param threadId - Optional thread ID for session-bound tokens.
+     * @returns The MCP access token response.
+     */
+    getMcpToken(contextKey?: string, threadId?: string): Promise<{
+        mcpAccessToken?: string;
+        expiresAt?: number;
+        hasSession?: boolean;
+    }>;
+    /**
+     * List suggestions for a message.
+     * @param messageId - The message ID.
+     * @param threadId - The thread ID.
+     * @returns Array of suggestions.
+     */
+    listSuggestions(messageId: string, threadId: string): Promise<Suggestion[]>;
+    /**
+     * Generate suggestions for a message.
+     * @param messageId - The message ID.
+     * @param threadId - The thread ID.
+     * @param options - Generation options.
+     * @param options.maxSuggestions - Maximum number of suggestions to generate.
+     * @returns Array of generated suggestions.
+     */
+    generateSuggestions(messageId: string, threadId: string, options?: {
+        maxSuggestions?: number;
+    }): Promise<Suggestion[]>;
+    /**
+     * Add a context helper that provides additional context on each run.
+     * @param name - Unique name for the helper.
+     * @param fn - Function returning context data.
+     */
+    addContextHelper(name: string, fn: ContextHelperFn): void;
+    /**
+     * Remove a context helper.
+     * @param name - The helper name to remove.
+     */
+    removeContextHelper(name: string): void;
+    /**
+     * Get the underlying SDK client (for advanced use cases).
+     * @returns The TamboAI SDK client.
+     */
+    getSdkClient(): TamboAI;
+    /**
+     * Dispatch an action to the state reducer and notify listeners.
+     * @param action - The action to dispatch.
+     */
+    private dispatch;
+    /**
+     * Batch subscriber notifications via queueMicrotask to reduce
+     * re-renders during high-frequency streaming.
+     */
+    private notifyListeners;
+    /**
+     * Resolve the base URL from an environment preset.
+     * @param environment - The environment to resolve.
+     * @returns The resolved base URL.
+     */
+    private resolveBaseUrl;
+    /**
+     * Merge context from registered context helpers with provided additional context.
+     * @param additionalContext - Context provided by the caller.
+     * @returns Merged context object.
+     */
+    private mergeContextForRun;
+}
+//# sourceMappingURL=tambo-client.d.ts.map

package/dist/tambo-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tambo-client.d.ts","sourceRoot":"","sources":["../src/tambo-client.ts"],"names":[],"mappings":"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"}