@useago/sdk 0.3.2 → 0.3.3

package/dist/index.d.ts

@@ -1,20 +1,1150 @@
-export { AgoClient } from "./client/AgoClient";
-export type { AgoAgent, AgoClientEvents, AgoConfig, AgoEventHandler, AgoEventName, AgoMessage, AgoSource, ClientFunction, ClientFunctionInvocation, Conversation, FormField, FormSchema, FunctionDefinition, FunctionSchema, MessageStatus, SendMessageOptions, SSEChunkData, ToolCallData, ToolCallType, } from "./client/types";
-export { AgoApiError, AgoError, AgoFunctionError, AgoNetworkError, AgoStreamError, } from "./client/errors";
-export { createStore } from "./state/createStore";
-export type { Store, PersistOptions } from "./state/createStore";
-export { ClientContextRegistry } from "./state/ClientContextRegistry";
-export type { ContextEntry, ContextSnapshot, DynamicContextProvider, } from "./state/ClientContextRegistry";
-export { defineFunction } from "./functions/defineFunction";
-export { FunctionRegistry } from "./functions/FunctionRegistry";
-export type { ClientFunctionDefinition, ClientFunctionHandler, ClientFunctionSchema, RegisteredFunction, } from "./functions/types";
-export { createMockClient } from "./testing";
-export type { MockAgoClient, MockAgoClientOptions } from "./testing";
-export { isStreamNetworkError, SSEHandler } from "./streaming/SSEHandler";
-export type { AgoWidgetColors, AgoWidgetConfig } from "./widget/types";
-export { createMessageStream, onFunctionInvoke, onMessage, onMessageChunk, onMessageError, onMessageStart, onToolCall, } from "./streaming/helpers";
-export { autoDetectConfig, createAgo } from "./auto/createAgo";
-export { copyToClipboard, getLocalStorage, getUserLocation, highlightElement, openUrl, scrollToElement, setLocalStorage, setTheme, showConfirmDialog, showNotification, showToast, submitForm, trackEvent, } from "./helpers/functions";
-export { withHandler } from "./helpers/factory";
-export { EventEmitter } from "./utils/eventEmitter";
-export { logger } from "./utils/logger";
+/**
+ * Agent information
+ */
+export declare interface AgoAgent {
+    id: string;
+    name: string;
+    displayName?: string;
+}
+
+/**
+ * Error from API response
+ */
+export declare class AgoApiError extends AgoError {
+    type: string;
+    param?: string | undefined;
+    docUrl?: string | undefined;
+    constructor(message: string, code: string, statusCode: number, type: string, param?: string | undefined, docUrl?: string | undefined);
+    static fromResponse(data: ApiErrorResponse, statusCode: number): AgoApiError;
+}
+
+/**
+ * Main SDK client for AGO Chat integration
+ */
+export declare class AgoClient {
+    private httpClient;
+    private functionRegistry;
+    private contextRegistry;
+    private eventEmitter;
+    private config;
+    constructor(config: AgoConfig);
+    /**
+     * Send a message and receive a streaming response
+     */
+    sendMessage(content: string, options?: SendMessageOptions): Promise<AgoMessage>;
+    private processSSEResponse;
+    private handleClientFunctionInvocation;
+    /**
+     * Get list of conversations
+     */
+    getConversations(): Promise<Conversation[]>;
+    /**
+     * Get a specific conversation with messages
+     */
+    getConversation(conversationId: string): Promise<Conversation>;
+    /**
+     * Get messages for a conversation
+     */
+    getMessages(conversationId: string): Promise<AgoMessage[]>;
+    /**
+     * Submit form data for a tool call
+     */
+    submitToolCallForm(toolCallId: string, formData: Record<string, unknown>): Promise<void>;
+    /**
+     * Confirm a tool call
+     */
+    confirmToolCall(toolCallId: string): Promise<void>;
+    /**
+     * Reject a tool call
+     */
+    rejectToolCall(toolCallId: string): Promise<void>;
+    /**
+     * Relay a completed form collector's values to a server-configured destination.
+     *
+     * Used by `createFormCollector` / `useFormCollector` in `{ via: "backend" }` mode:
+     * the browser never holds the destination URL or its secret — the backend resolves
+     * `destination` (a named, opted-in tool) and forwards the values from the server.
+     */
+    submitFormCollector(destination: string, values: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Submit feedback for a message
+     */
+    submitFeedback(messageId: string, rating: "positive" | "negative"): Promise<void>;
+    /**
+     * Register a client-side function that AGO can call.
+     * Accepts either a definition object or (name, handler, schema) args.
+     *
+     * ```ts
+     * // Single-object (preferred)
+     * client.registerFunction({
+     *   name: "lookupOrder",
+     *   description: "Look up an order",
+     *   parameters: { type: "object", properties: { id: { type: "string" } } },
+     *   handler: async (args) => fetchOrder(args.id),
+     * });
+     *
+     * // Classic 3-arg form
+     * client.registerFunction("lookupOrder", handler, schema);
+     * ```
+     */
+    registerFunction(definition: ClientFunctionDefinition): void;
+    registerFunction(name: string, handler: ClientFunctionHandler, schema: Omit<ClientFunctionSchema, "name">): void;
+    /**
+     * Short alias for `registerFunction`. Also accepts an array of definitions.
+     *
+     * ```ts
+     * client.register(lookupOrder);
+     * client.register([lookupOrder, cancelOrder]);
+     * ```
+     */
+    register(definition: ClientFunctionDefinition | ClientFunctionDefinition[]): void;
+    /**
+     * Unregister a client-side function
+     */
+    unregisterFunction(name: string): boolean;
+    /**
+     * Get all registered function schemas
+     */
+    getRegisteredFunctions(): ClientFunctionSchema[];
+    /**
+     * Register a navigation function that lets AGO navigate users to different pages.
+     * @param navigate - A callback that performs the navigation (e.g. react-router's navigate)
+     * @param routes - Map of route names to paths, with descriptions for the LLM
+     */
+    registerNavigationFunction(navigate: (path: string) => void, routes: Array<{
+        name: string;
+        path: string;
+        description: string;
+    }>): void;
+    /**
+     * Register or update a piece of client-side context.
+     * This context is sent with every message so the AI understands the user's situation.
+     *
+     * ```ts
+     * client.setContext("order-page", {
+     *   name: "Order detail",
+     *   description: "User is viewing order #123",
+     *   data: { orderId: "123", status: "shipped" },
+     * });
+     * ```
+     */
+    setContext(key: string, entry: ContextEntry): void;
+    /**
+     * Remove a previously registered context entry.
+     */
+    removeContext(key: string): boolean;
+    /**
+     * Register a dynamic context provider. The callback is invoked every time
+     * a message is sent, so the AI always gets the freshest data.
+     *
+     * Use this for context that lives outside React state — global stores,
+     * refs, or computed values.
+     *
+     * ```ts
+     * client.addDynamicContext("cart", () => ({
+     *   name: "Checkout",
+     *   data: { itemCount: cart.items.length, total: cart.total },
+     * }));
+     * ```
+     */
+    addDynamicContext(key: string, provider: DynamicContextProvider): void;
+    /**
+     * Remove a dynamic context provider.
+     */
+    removeDynamicContext(key: string): boolean;
+    /**
+     * Enable automatic capture of the current browser page (URL + title).
+     * Injected as a dynamic context entry named `browser-page`.
+     */
+    enableAutoPageContext(): void;
+    /**
+     * Get the current context snapshot.
+     */
+    getContextSnapshot(): ContextSnapshot | null;
+    /**
+     * Subscribe to an event
+     */
+    on<K extends AgoEventName>(event: K, handler: AgoEventHandler<K>): void;
+    /**
+     * Unsubscribe from an event
+     */
+    off<K extends AgoEventName>(event: K, handler: AgoEventHandler<K>): void;
+    /**
+     * Subscribe to an event once — auto-unsubscribes after the first call.
+     */
+    once<K extends AgoEventName>(event: K, handler: AgoEventHandler<K>): void;
+    /**
+     * Returns a Promise that resolves the next time `event` fires.
+     *
+     * ```ts
+     * const msg = await client.waitFor("message:complete", { timeout: 10000 });
+     * ```
+     */
+    waitFor<K extends AgoEventName>(event: K, options?: {
+        timeout?: number;
+    }): Promise<AgoClientEvents[K]>;
+    /**
+     * Update client configuration
+     */
+    updateConfig(config: Partial<AgoConfig>): void;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}
+
+/**
+ * SDK Events
+ */
+export declare interface AgoClientEvents {
+    "message:start": {
+        conversationId: string;
+        messageId: string;
+    };
+    "message:chunk": {
+        content: string;
+        conversationId: string;
+        messageId: string;
+    };
+    "message:complete": AgoMessage;
+    "message:error": {
+        error: string;
+        conversationId?: string;
+        messageId?: string;
+    };
+    "toolCall:received": ToolCallData;
+    "toolCall:form": ToolCallData;
+    "function:invoke": ClientFunctionInvocation;
+    "function:result": {
+        invocationId: string;
+        result: unknown;
+        error?: string;
+    };
+    "connection:status": {
+        connected: boolean;
+    };
+}
+
+/**
+ * SDK Configuration
+ */
+export declare interface AgoConfig {
+    /** API base URL (e.g., https://YOUR-DOMAIN.useago.com) */
+    baseUrl: string;
+    /** Widget ID (X-Widget-Id header). Auto-generated if not provided. */
+    widgetId?: string;
+    /** Default agent (id or slug) for new conversations. Shorthand for `defaultAgentId`. */
+    agent?: string;
+    /** Default agent ID for new conversations. Prefer `agent`. */
+    defaultAgentId?: string;
+    /** Permission name to apply to all requests (sent as `X-Widget-Permission`). Mirrors the widget's `window.AGO.permission`. */
+    permission?: string;
+    /** User email for identification */
+    userEmail?: string;
+    /** JWT token for authenticated users */
+    userJwt?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+
+/**
+ * Base error class for AGO SDK
+ */
+export declare class AgoError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined);
+}
+
+export declare type AgoEventHandler<K extends AgoEventName> = (data: AgoClientEvents[K]) => void;
+
+export declare type AgoEventName = keyof AgoClientEvents;
+
+/**
+ * Function execution error
+ */
+export declare class AgoFunctionError extends AgoError {
+    functionName: string;
+    originalError?: Error | undefined;
+    constructor(message: string, functionName: string, originalError?: Error | undefined);
+}
+
+/**
+ * Message from AGO
+ */
+export declare interface AgoMessage {
+    id: string;
+    conversationId: string;
+    content: string;
+    role: "user" | "assistant";
+    status: MessageStatus;
+    agent?: AgoAgent;
+    sources?: AgoSource[];
+    toolCalls?: ToolCallData[];
+    followUpReplies?: string[];
+    createdAt: Date;
+}
+
+/**
+ * Network/connection error
+ */
+export declare class AgoNetworkError extends AgoError {
+    originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+
+/**
+ * Knowledge source citation
+ */
+export declare interface AgoSource {
+    id: string;
+    title: string;
+    url?: string;
+}
+
+/**
+ * SSE stream error
+ */
+export declare class AgoStreamError extends AgoError {
+    constructor(message: string);
+}
+
+/**
+ * Widget configuration types.
+ *
+ * These types describe the `window.AGO` configuration object
+ * used by the embeddable chat widget snippet.
+ *
+ * @example
+ * ```ts
+ * import type { AgoWidgetConfig } from "@useago/sdk/widget";
+ * ```
+ */
+export declare interface AgoWidgetColors {
+    button?: string;
+    header?: string;
+    agentMessage?: string;
+    agentMessageFont?: string;
+    background?: string;
+    font?: string;
+    userMessage?: string;
+    userMessageFont?: string;
+}
+
+export declare interface AgoWidgetConfig {
+    basepath: string;
+    widgetApiKey: string;
+    defaultAgent?: string;
+    email?: string;
+    title?: string;
+    icon?: string;
+    prompt?: string;
+    notifications?: boolean;
+    notificationMessage?: string;
+    colors?: AgoWidgetColors;
+    hideFooter?: boolean;
+    jwt?: string;
+    authToken?: string;
+    permission?: string;
+    metadata?: Record<string, unknown>;
+}
+
+declare interface ApiErrorResponse {
+    error: {
+        type: string;
+        code: string;
+        message: string;
+        param?: string;
+        doc_url?: string;
+    };
+}
+
+/**
+ * Auto-detect AGO configuration from the DOM environment.
+ *
+ * Checks (in order of priority):
+ * 1. `window.AGO` global object (widget config)
+ * 2. `<meta>` tags: `<meta name="ago-api-key" content="...">`
+ * 3. `data-ago-*` attributes on `<body>` or `<script data-ago-api-key="...">`
+ * 4. Explicit overrides passed as argument
+ *
+ * Returns null if no API key can be found.
+ */
+export declare function autoDetectConfig(overrides?: Partial<AgoConfig>): AgoConfig | null;
+
+/**
+ * Registry that collects client-side context from across the component tree.
+ *
+ * Components register/unregister context slices via unique keys.
+ * When a message is sent the registry produces a single snapshot.
+ */
+export declare class ClientContextRegistry {
+    private entries;
+    private dynamicProviders;
+    /**
+     * Register or update a static context entry.
+     */
+    set(key: string, entry: ContextEntry): void;
+    /**
+     * Remove a static context entry (typically on component unmount).
+     */
+    remove(key: string): boolean;
+    /**
+     * Register a dynamic context provider. The function is called every time
+     * a message is sent, so it always returns the freshest data.
+     *
+     * Use this for context that lives outside React state — global stores,
+     * refs, or computed values that shouldn't trigger re-renders.
+     */
+    addDynamicProvider(key: string, provider: DynamicContextProvider): void;
+    /**
+     * Remove a dynamic context provider.
+     */
+    removeDynamicProvider(key: string): boolean;
+    /**
+     * Build a snapshot of the current client context.
+     * Evaluates every registered dynamic provider. Returns `null` when there is
+     * nothing to report.
+     */
+    getSnapshot(): ContextSnapshot | null;
+    /**
+     * Remove all entries and dynamic providers.
+     */
+    clear(): void;
+}
+
+export declare type ClientFunction = (args: Record<string, unknown>) => Promise<unknown> | unknown;
+
+/**
+ * Single-object function definition — combines name, schema, and handler.
+ *
+ * ```ts
+ * const fn = defineFunction({
+ *   name: "lookupOrder",
+ *   description: "Look up an order by ID",
+ *   parameters: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+ *   handler: async (args) => fetchOrder(args.id as string),
+ * });
+ * client.registerFunction(fn);
+ * ```
+ */
+export declare interface ClientFunctionDefinition {
+    name: string;
+    description: string;
+    parameters: ClientFunctionSchema["parameters"];
+    handler: ClientFunctionHandler;
+}
+
+/**
+ * Function handler type
+ */
+export declare type ClientFunctionHandler = (args: Record<string, unknown>) => Promise<unknown> | unknown;
+
+export declare interface ClientFunctionInvocation {
+    invocationId: string;
+    functionName: string;
+    arguments: Record<string, unknown>;
+    conversationId: string;
+}
+
+/**
+ * Schema for a client-side function that AGO can call
+ */
+export declare interface ClientFunctionSchema {
+    /** Function name (must be unique) */
+    name: string;
+    /** Description for the LLM to understand when to call this function */
+    description: string;
+    /** JSON Schema for function parameters */
+    parameters: {
+        type: "object";
+        properties: Record<string, {
+            type: string;
+            description?: string;
+            enum?: string[];
+            default?: unknown;
+        }>;
+        required?: string[];
+    };
+}
+
+/**
+ * A single piece of context the client wants the LLM to know about.
+ */
+export declare interface ContextEntry {
+    /** Human-readable label (e.g. "Order detail", "Current user") */
+    name?: string;
+    /** Short description of what this context represents */
+    description?: string;
+    /** Arbitrary structured data the AI should know about */
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Serialised client context sent with each message.
+ */
+export declare interface ContextSnapshot {
+    /** All active context entries keyed by their registration key */
+    entries: Record<string, ContextEntry>;
+}
+
+/**
+ * Conversation/Thread
+ */
+export declare interface Conversation {
+    id: string;
+    title: string;
+    lastMessageDate: Date;
+    messages?: AgoMessage[];
+}
+
+/**
+ * Copy text to clipboard.
+ */
+export declare const copyToClipboard: ClientFunctionDefinition;
+
+/**
+ * Create an AgoClient with zero configuration.
+ * Auto-detects config from window.AGO, meta tags, and data-ago-* attributes.
+ *
+ * ```html
+ * <!-- In your HTML -->
+ * <meta name="ago-base-url" content="https://YOUR-DOMAIN.useago.com">
+ *
+ * <!-- Or on a script tag -->
+ * <script src="app.js" data-ago-base-url="https://YOUR-DOMAIN.useago.com"></script>
+ * ```
+ *
+ * ```ts
+ * import { createAgo } from "@useago/sdk";
+ *
+ * // Zero config — picks up from DOM
+ * const client = createAgo();
+ *
+ * // Or with partial overrides
+ * const client = createAgo({ debug: true });
+ * ```
+ *
+ * Throws if no base URL can be detected.
+ */
+export declare function createAgo(overrides?: Partial<AgoConfig>): AgoClient;
+
+/**
+ * Wire one schema into a conversational form: an observable store, an
+ * `update_<name>` client function the agent calls to fill fields, a dynamic-context
+ * provider that tells the agent what's still missing, and an optional submit.
+ *
+ * ```ts
+ * const order = createFormCollector({
+ *   name: "order",
+ *   description: "The order the user wants to place",
+ *   schema: {
+ *     type: "object",
+ *     properties: { product: { type: "string" }, quantity: { type: "number" } },
+ *     required: ["product", "quantity"],
+ *   },
+ *   submit: { via: "client", url: "/api/orders" },
+ * });
+ * order.install(client);
+ * order.store.subscribe((s) => render(s));
+ * ```
+ */
+export declare function createFormCollector<V = Record<string, unknown>>(options: CreateFormCollectorOptions<V>): FormCollector<V>;
+
+export declare interface CreateFormCollectorOptions<V = Record<string, unknown>> {
+    /** Short identifier; becomes the `update_<name>` / `submit_<name>` function names. */
+    name: string;
+    /** What the form is, for the LLM. */
+    description: string;
+    /** The single source of truth for the form's fields. */
+    schema: FormCollectorSchema;
+    /** How the completed form is submitted. Default: `false` (collect only). */
+    submit?: SubmitConfig<V>;
+    /** Pre-filled values. */
+    initialValues?: Partial<V>;
+}
+
+/**
+ * Send a message and iterate over chunks as an async generator.
+ * Gives you full control over how you process the stream.
+ *
+ * ```ts
+ * for await (const chunk of createMessageStream(client, "Hello!")) {
+ *   console.log(chunk.type, chunk.data);
+ * }
+ * ```
+ */
+export declare function createMessageStream(client: AgoClient, content: string, options?: {
+    conversationId?: string;
+    agentId?: string;
+    files?: File[];
+}): AsyncGenerator<{
+    type: "start";
+    data: AgoClientEvents["message:start"];
+} | {
+    type: "chunk";
+    data: AgoClientEvents["message:chunk"];
+} | {
+    type: "complete";
+    data: AgoMessage;
+} | {
+    type: "error";
+    data: AgoClientEvents["message:error"];
+} | {
+    type: "toolCall";
+    data: ToolCallData;
+}>;
+
+/**
+ * Create a mock AgoClient for testing. Works with any framework.
+ *
+ * ```ts
+ * import { createMockClient } from "@useago/sdk/testing";
+ *
+ * const mock = createMockClient();
+ * mock.__emitEvent("message:complete", someMessage);
+ * expect(mock.__callsFor("sendMessage")).toHaveLength(1);
+ * ```
+ */
+export declare function createMockClient(options?: MockAgoClientOptions): MockAgoClient;
+
+export declare function createStore<T>(initial: T, persist?: PersistOptions): Store<T>;
+
+/**
+ * Create a reusable function definition.
+ * Returns the same object — this is an identity function for discoverability and type-checking.
+ *
+ * ```ts
+ * // Define once, reuse anywhere
+ * export const lookupOrder = defineFunction({
+ *   name: "lookupOrder",
+ *   description: "Look up an order by ID",
+ *   parameters: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+ *   handler: async (args) => fetchOrder(args.id as string),
+ * });
+ *
+ * // Register with client
+ * client.registerFunction(lookupOrder);
+ *
+ * // Or use in React
+ * useAgoFunction(lookupOrder.name, lookupOrder);
+ * ```
+ */
+export declare function defineFunction(definition: ClientFunctionDefinition): ClientFunctionDefinition;
+
+/**
+ * A function that returns a fresh context entry on demand.
+ * Evaluated every time a message is sent — use it to pull data from stores,
+ * refs, or any source that isn't captured by React state.
+ */
+export declare type DynamicContextProvider = () => ContextEntry | null | undefined;
+
+/**
+ * Simple typed event emitter
+ */
+export declare class EventEmitter<Events extends Record<string, any> = Record<string, unknown>> {
+    private handlers;
+    on<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): void;
+    off<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): void;
+    emit<K extends keyof Events>(event: K, data: Events[K]): void;
+    /**
+     * Subscribe to an event and auto-unsubscribe after the first call.
+     */
+    once<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): void;
+    /**
+     * Returns a Promise that resolves the next time `event` fires.
+     * Rejects if `timeout` (ms) is reached first.
+     */
+    waitFor<K extends keyof Events>(event: K, options?: {
+        timeout?: number;
+    }): Promise<Events[K]>;
+    removeAllListeners(event?: keyof Events): void;
+}
+
+declare type EventHandler<T = unknown> = (data: T) => void;
+
+export declare interface FormCollector<V = Record<string, unknown>> {
+    name: string;
+    /** Observable store driving the form UI (read via `useAgoStore`). */
+    store: Store<FormCollectorState<V>>;
+    /** Client functions to register: `[update]` or `[update, submit]`. */
+    functions: ClientFunctionDefinition[];
+    /** Dynamic-context key under which the form state is exposed. */
+    contextKey: string;
+    /** Dynamic-context provider — re-read on every message. */
+    contextProvider: () => ContextEntry;
+    /** Register the functions + dynamic context on a client. Returns an uninstall fn. */
+    install: (client: AgoClient) => () => void;
+    /** Submit the form now (e.g. from a UI button). Blocks until required fields are filled. */
+    submit: () => Promise<FormSubmitResult>;
+    getValues: () => Partial<V>;
+    setValues: (patch: Partial<V>) => void;
+    reset: () => void;
+}
+
+/**
+ * JSON-schema shape of a form's fields — identical to a client function's
+ * `parameters`, so one schema feeds the store, the update function, and the
+ * dynamic context with no second type.
+ */
+export declare type FormCollectorSchema = ClientFunctionSchema["parameters"];
+
+/** Live state held in the collector's store. */
+export declare interface FormCollectorState<V = Record<string, unknown>> {
+    /** Field values collected so far. */
+    values: Partial<V>;
+    /** Required field names still empty. */
+    missing: string[];
+    /** True when no required field is missing. */
+    complete: boolean;
+    /** True once a submit succeeded. */
+    submitted: boolean;
+}
+
+export declare interface FormField {
+    type: "string" | "number" | "boolean" | "array";
+    title?: string;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+}
+
+/**
+ * Form schema for tool calls requiring user input
+ */
+export declare interface FormSchema {
+    type: "object";
+    properties: Record<string, FormField>;
+    required?: string[];
+}
+
+/** Result returned by `submit()` / the generated `submit_<name>` function. */
+export declare interface FormSubmitResult {
+    ok: boolean;
+    missing?: string[];
+    result?: unknown;
+    error?: string;
+}
+
+export declare interface FunctionDefinition {
+    name: string;
+    schema: FunctionSchema;
+    handler: ClientFunction;
+}
+
+/**
+ * Registry for client-side functions that AGO can call
+ */
+export declare class FunctionRegistry {
+    private functions;
+    /**
+     * Register a function that AGO can call.
+     * Accepts either a single definition object or (name, handler, schema) args.
+     */
+    register(definition: ClientFunctionDefinition): void;
+    register(name: string, handler: ClientFunctionHandler, schema: Omit<ClientFunctionSchema, "name">): void;
+    /**
+     * Unregister a function
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get a registered function
+     */
+    get(name: string): RegisteredFunction | undefined;
+    /**
+     * Check if a function is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered function schemas (for sending to backend)
+     */
+    getSchemas(): ClientFunctionSchema[];
+    /**
+     * Execute a registered function
+     */
+    execute(name: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Clear all registered functions
+     */
+    clear(): void;
+    /**
+     * Get the number of registered functions
+     */
+    get size(): number;
+}
+
+/**
+ * Client-side function types
+ */
+export declare interface FunctionSchema {
+    name: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: Record<string, {
+            type: string;
+            description?: string;
+            enum?: string[];
+        }>;
+        required?: string[];
+    };
+}
+
+/**
+ * Get a value from localStorage.
+ */
+export declare const getLocalStorage: ClientFunctionDefinition;
+
+/**
+ * Get the user's geolocation.
+ */
+export declare const getUserLocation: ClientFunctionDefinition;
+
+/**
+ * Highlight an element on the page (useful for guided tours).
+ */
+export declare const highlightElement: ClientFunctionDefinition;
+
+/**
+ * Check if an error is a network error that should trigger polling fallback
+ */
+export declare function isStreamNetworkError(error: Error): boolean;
+
+/**
+ * Debug logger for SDK
+ */
+declare class Logger {
+    private enabled;
+    constructor(enabled?: boolean);
+    enable(): void;
+    disable(): void;
+    log(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+
+export declare const logger: Logger;
+
+export declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED";
+
+export declare interface MockAgoClient extends AgoClient {
+    /**
+     * Simulate a server-pushed event.
+     * ```ts
+     * mock.__emitEvent("message:complete", { id: "1", content: "hi", ... });
+     * ```
+     */
+    __emitEvent<K extends AgoEventName>(event: K, data: AgoClientEvents[K]): void;
+    /**
+     * All recorded method calls: `[methodName, ...args][]`
+     */
+    __calls: Array<{
+        method: string;
+        args: unknown[];
+    }>;
+    /**
+     * Get calls for a specific method.
+     */
+    __callsFor(method: string): Array<{
+        method: string;
+        args: unknown[];
+    }>;
+}
+
+export declare interface MockAgoClientOptions {
+    overrides?: Partial<Record<string, MockFn>>;
+}
+
+declare type MockFn = (...args: any[]) => any;
+
+/**
+ * Subscribe to client function invocations.
+ */
+export declare function onFunctionInvoke(client: AgoClient, callback: (data: ClientFunctionInvocation) => void): () => void;
+
+/**
+ * Subscribe to complete messages with a simple callback. Returns an unsubscribe function.
+ *
+ * ```ts
+ * const unsub = onMessage(client, (msg) => console.log(msg.content));
+ * // later: unsub();
+ * ```
+ */
+export declare function onMessage(client: AgoClient, callback: (message: AgoMessage) => void): () => void;
+
+/**
+ * Subscribe to streaming text chunks.
+ *
+ * ```ts
+ * onMessageChunk(client, ({ content }) => {
+ *   outputEl.textContent += content;
+ * });
+ * ```
+ */
+export declare function onMessageChunk(client: AgoClient, callback: (data: AgoClientEvents["message:chunk"]) => void): () => void;
+
+/**
+ * Subscribe to message errors.
+ */
+export declare function onMessageError(client: AgoClient, callback: (data: AgoClientEvents["message:error"]) => void): () => void;
+
+/**
+ * Subscribe to message start events.
+ */
+export declare function onMessageStart(client: AgoClient, callback: (data: AgoClientEvents["message:start"]) => void): () => void;
+
+/**
+ * Subscribe to tool call events.
+ */
+export declare function onToolCall(client: AgoClient, callback: (toolCall: ToolCallData) => void): () => void;
+
+/**
+ * Open a URL in a new tab.
+ */
+export declare const openUrl: ClientFunctionDefinition;
+
+export declare interface PersistOptions {
+    /** Key under which the state is JSON-serialized. */
+    key: string;
+    /** Storage backend; defaults to `globalThis.localStorage`. */
+    storage?: StorageLike;
+}
+
+/**
+ * Registered function with handler
+ */
+export declare interface RegisteredFunction {
+    schema: ClientFunctionSchema;
+    handler: ClientFunctionHandler;
+}
+
+/**
+ * Scroll to an element on the page.
+ */
+export declare const scrollToElement: ClientFunctionDefinition;
+
+/**
+ * Options for sending a message
+ */
+export declare interface SendMessageOptions {
+    /** Existing conversation ID */
+    conversationId?: string;
+    /** Override default agent */
+    agentId?: string;
+    /** File attachments */
+    files?: File[];
+}
+
+/**
+ * Set a value in localStorage.
+ */
+export declare const setLocalStorage: ClientFunctionDefinition;
+
+/**
+ * Set the application theme (light/dark/system).
+ * Default handler toggles a `data-theme` attribute on `<html>`.
+ */
+export declare const setTheme: ClientFunctionDefinition;
+
+/**
+ * Show a confirm dialog and return the user's choice.
+ */
+export declare const showConfirmDialog: ClientFunctionDefinition;
+
+/**
+ * Show a browser notification (requires permission).
+ */
+export declare const showNotification: ClientFunctionDefinition;
+
+/**
+ * Show a toast/notification to the user.
+ * The handler is a no-op by default — wire it up to your toast library.
+ *
+ * ```ts
+ * import { showToast } from "@useago/sdk/helpers";
+ * showToast.handler = async (args) => { myToast(args.message); return { shown: true }; };
+ * client.registerFunction(showToast);
+ * ```
+ */
+export declare const showToast: ClientFunctionDefinition;
+
+/**
+ * SSE stream chunk data
+ */
+export declare interface SSEChunkData {
+    content?: string;
+    full_content?: string;
+    message_id?: string;
+    status?: MessageStatus;
+    thread?: {
+        id: string;
+    };
+    agent?: {
+        id: string;
+        name: string;
+        display_name?: string;
+    };
+    knowledge_sources?: Array<{
+        knowledge_document: {
+            id: string;
+            title: string;
+            use_external_link: boolean;
+            external_link_url?: string;
+            internal_link_url?: string;
+        };
+        position: number;
+    }>;
+    tool_call_data?: boolean;
+    type?: string;
+    id?: string;
+    tool_name?: string;
+    tool_display_name?: string;
+    function_name?: string;
+    arguments?: Record<string, unknown>;
+    form_schema?: FormSchema;
+    message?: string;
+    data?: Record<string, unknown>;
+    follow_up_replies?: string[];
+    satisfaction_feedback?: unknown;
+    ask_to_talk_to_human?: boolean;
+}
+
+/**
+ * Handles SSE streaming responses from AGO backend
+ */
+export declare class SSEHandler {
+    private callbacks;
+    private buffer;
+    private message;
+    private toolCalls;
+    private sources;
+    private followUpReplies;
+    private isFirstChunk;
+    constructor(callbacks: SSEHandlerCallbacks);
+    /**
+     * Process a streaming response
+     */
+    processStream(response: Response): Promise<AgoMessage>;
+    private processBuffer;
+    private handleChunk;
+    private parseToolCall;
+    private buildFinalMessage;
+}
+
+declare interface SSEHandlerCallbacks {
+    onStart?: (data: {
+        conversationId: string;
+        messageId: string;
+    }) => void;
+    onChunk?: (data: {
+        content: string;
+        conversationId: string;
+        messageId: string;
+    }) => void;
+    onToolCall?: (toolCall: ToolCallData) => void;
+    onClientFunction?: (data: {
+        invocationId: string;
+        functionName: string;
+        arguments: Record<string, unknown>;
+        conversationId: string;
+    }) => void;
+    onComplete?: (message: AgoMessage) => void;
+    onError?: (error: Error) => void;
+}
+
+/** The slice of the Web Storage API that {@link createStore} relies on. */
+declare type StorageLike = Pick<Storage, "getItem" | "setItem">;
+
+/**
+ * A minimal observable store: one value, synchronous subscriptions, and
+ * optional persistence via {@link PersistOptions} (localStorage by default).
+ *
+ * ```ts
+ * const store = createStore({ count: 0 });
+ * store.subscribe((state) => save(state));
+ * store.set({ count: 1 }); // listeners fire synchronously
+ *
+ * const cart = createStore({ items: [] }, { key: "cart" }); // persisted
+ * ```
+ */
+export declare interface Store<T> {
+    /** Current state. */
+    get(): T;
+    /** Replace the state and notify subscribers synchronously. */
+    set(next: T): void;
+    /** Register a listener; returns a function that removes it. */
+    subscribe(listener: (state: T) => void): () => void;
+}
+
+/**
+ * Where a completed form is sent.
+ * - `"https://..."` (a bare string) — shorthand for `{ via: "client", url }`: the browser
+ *   POSTs the values to that URL.
+ * - `{ via: "client", url }` — same, written out.
+ * - `{ via: "client", handler }` — the browser runs your own submit logic.
+ * - `{ via: "backend", destination }` — the browser relays the values to the backend,
+ *   which forwards them to the server-configured destination (URL + secret stay server-side).
+ * - `false` — collect only, no submit function.
+ */
+export declare type SubmitConfig<V = Record<string, unknown>> = string | {
+    via: "client";
+    url: string;
+} | {
+    via: "client";
+    handler: (values: V) => Promise<unknown> | unknown;
+} | {
+    via: "backend";
+    destination: string;
+} | false;
+
+/**
+ * Submit a form on the page programmatically.
+ */
+export declare const submitForm: ClientFunctionDefinition;
+
+/**
+ * Tool call data from SSE stream
+ */
+export declare interface ToolCallData {
+    id: string;
+    type: ToolCallType;
+    status: string;
+    toolName: string;
+    toolDisplayName?: string;
+    message?: string;
+    formSchema?: FormSchema;
+    data?: Record<string, unknown>;
+    functionName?: string;
+    arguments?: Record<string, unknown>;
+}
+
+export declare type ToolCallType = "form" | "confirmation_input" | "status_message" | "progress_indicator" | "client_function" | "reasoning" | "mcp_ui_resource";
+
+/**
+ * Track a custom analytics event.
+ * Default handler logs to console — replace with your analytics provider.
+ */
+export declare const trackEvent: ClientFunctionDefinition;
+
+/**
+ * Attach a handler to a pre-built function definition.
+ *
+ * Pre-built helpers (`showToast`, `trackEvent`, ...) ship with a no-op or
+ * console-logging default handler. Use `withHandler` to wire them up to
+ * your actual implementation without mutating the original definition.
+ *
+ * ```ts
+ * import { showToast, withHandler } from "@useago/sdk";
+ *
+ * client.register(
+ *   withHandler(showToast, (args) => {
+ *     myToast(args.message as string);
+ *     return { shown: true };
+ *   })
+ * );
+ * ```
+ */
+export declare function withHandler<T extends ClientFunctionDefinition>(definition: T, handler: ClientFunctionHandler): T;
+
+export { }