@useago/sdk 0.3.3 → 0.4.1

package/dist/widget.d.ts

@@ -1,3 +1,282 @@
+/**
+ * Agent information
+ */
+declare interface AgoAgent {
+    id: string;
+    name: string;
+    displayName?: string;
+}
+
+/**
+ * Main SDK client for AGO Chat integration
+ */
+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>;
+    /**
+     * Map the backend's snake_case `tool_call_data` entries onto the camelCase
+     * {@link ToolCallData} shape used everywhere else in the SDK. Mirrors
+     * `SSEHandler.parseToolCall` so persisted and streamed tool calls match.
+     */
+    private static mapPersistedToolCalls;
+    /**
+     * 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
+ */
+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;
+    };
+    /**
+     * A full conversation was loaded from the server (e.g. after a page reload).
+     * Carries the messages and their persisted tool calls so stateful helpers —
+     * notably `createFormCollector` — can replay them to restore their state.
+     */
+    "conversation:loaded": Conversation;
+    "toolCall:received": ToolCallData;
+    "toolCall:form": ToolCallData;
+    "function:invoke": ClientFunctionInvocation;
+    "function:result": {
+        invocationId: string;
+        result: unknown;
+        error?: string;
+    };
+    "connection:status": {
+        connected: boolean;
+    };
+}
+
+/**
+ * SDK Configuration
+ */
+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;
+}
+
+declare type AgoEventHandler<K extends AgoEventName> = (data: AgoClientEvents[K]) => void;
+
+declare type AgoEventName = keyof AgoClientEvents;
+
+/**
+ * Message from AGO
+ */
+declare interface AgoMessage {
+    id: string;
+    conversationId: string;
+    content: string;
+    role: "user" | "assistant";
+    status: MessageStatus;
+    agent?: AgoAgent;
+    sources?: AgoSource[];
+    toolCalls?: ToolCallData[];
+    followUpReplies?: string[];
+    createdAt: Date;
+}
+
+/**
+ * Knowledge source citation
+ */
+declare interface AgoSource {
+    id: string;
+    title: string;
+    url?: string;
+}
+
 /**
  * Widget configuration types.
  *
@@ -38,4 +317,360 @@ export declare interface AgoWidgetConfig {
     metadata?: Record<string, unknown>;
 }
 
+/** Handle returned by {@link mountChatWidget}. */
+export declare interface ChatWidgetHandle {
+    /** The AGO client backing the widget. */
+    client: AgoClient;
+    /** The root element the widget rendered into. */
+    element: HTMLElement;
+    /** Programmatically send a message (same path as the input). */
+    sendMessage: (content: string, files?: File[]) => Promise<void>;
+    /**
+     * The conversation-persistence session, present only when `persistConversation`
+     * is set — exposes the stable `widgetId` and `session.clear()` to start a new thread.
+     */
+    session?: ConversationSession;
+    /**
+     * The visitor's conversations (threads) — the vanilla equivalent of the React/Vue
+     * `useConversation().conversations`. Auto-loaded on mount and refreshed after each
+     * turn only when `loadThreads` is set; otherwise it stays empty until you call
+     * {@link ChatWidgetHandle.refreshThreads}.
+     */
+    readonly threads: Conversation[];
+    /** Re-fetch the conversations list and update {@link ChatWidgetHandle.threads}. */
+    refreshThreads: () => Promise<Conversation[]>;
+    /** Remove listeners, uninstall forms, and clear the DOM. */
+    destroy: () => void;
+}
+
+/**
+ * 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);
+ * ```
+ */
+declare interface ClientFunctionDefinition {
+    name: string;
+    description: string;
+    parameters: ClientFunctionSchema["parameters"];
+    handler: ClientFunctionHandler;
+}
+
+/**
+ * Function handler type
+ */
+declare type ClientFunctionHandler = (args: Record<string, unknown>) => Promise<unknown> | unknown;
+
+declare interface ClientFunctionInvocation {
+    invocationId: string;
+    functionName: string;
+    arguments: Record<string, unknown>;
+    conversationId: string;
+}
+
+/**
+ * Schema for a client-side function that AGO can call
+ */
+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.
+ */
+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.
+ */
+declare interface ContextSnapshot {
+    /** All active context entries keyed by their registration key */
+    entries: Record<string, ContextEntry>;
+}
+
+/**
+ * Conversation/Thread
+ */
+declare interface Conversation {
+    id: string;
+    title: string;
+    lastMessageDate: Date;
+    messages?: AgoMessage[];
+}
+
+export declare interface ConversationSession {
+    /**
+     * The stable widget id identifying this visitor. Generated once and persisted
+     * forever, so a returning visitor keeps the same id (and therefore the same
+     * server-side conversation history) across reloads.
+     */
+    readonly widgetId: string;
+    /**
+     * The last active thread id, decided **entirely on the front** so a reload costs
+     * no backend round-trip. Returns `null` when there is no cached thread, when its
+     * last message time is unknown, or when it has been idle longer than `ttlMs`.
+     */
+    getLastActiveThread(): string | null;
+    /**
+     * Record (and refresh) the active thread together with the time of its last
+     * message — call it once per turn. The `lastMessageAt` drives the sliding TTL;
+     * omit it and the thread won't be resumed (no time → not displayed).
+     */
+    setActiveThread(conversationId: string, lastMessageAt?: Date | number): void;
+    /** Forget the cached thread — e.g. on "new chat". */
+    clear(): void;
+    /** The resolved storage key holding the widget id — handy for debugging. */
+    readonly key: string;
+}
+
+export declare interface ConversationSessionOptions {
+    /**
+     * Storage backend. Defaults to `localStorage`, degrading to an in-memory store
+     * when storage is unavailable (SSR / disabled). Pass `sessionStorage` for a
+     * tab-scoped session, or any `{ getItem, setItem }` for a custom backend.
+     */
+    storage?: StorageLike;
+    /**
+     * Storage key for the widget id. Default `"ago_widget_id"` — the same key the
+     * HTTP client reads, so the visitor's id is shared across the SDK.
+     */
+    key?: string;
+    /**
+     * Explicit widget id to adopt (and persist) instead of reading or generating
+     * one — e.g. when the host app already has a stable visitor identifier.
+     */
+    widgetId?: string;
+    /** Storage key for the cached last active thread. Default `"ago_last_thread"`. */
+    threadKey?: string;
+    /**
+     * Maximum idle age of a thread to still resume it, in milliseconds, compared
+     * against the recorded time of its last message. Checked entirely on the front
+     * (no backend call): a thread idle longer than this — or one with no recorded
+     * last-message time — is not resumed (`getLastActiveThread` returns `null`).
+     * Default 2h. Pass `Infinity` to never expire.
+     */
+    ttlMs?: number;
+}
+
+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>;
+}
+
+/**
+ * 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.
+ */
+declare type DynamicContextProvider = () => ContextEntry | null | undefined;
+
+/**
+ * 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.
+ */
+declare type FormCollectorSchema = ClientFunctionSchema["parameters"];
+
+declare interface FormField {
+    type: "string" | "number" | "boolean" | "array";
+    title?: string;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+}
+
+/**
+ * Form schema for tool calls requiring user input
+ */
+declare interface FormSchema {
+    type: "object";
+    properties: Record<string, FormField>;
+    required?: string[];
+}
+
+declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED";
+
+/**
+ * Mount a complete, dependency-free chat widget into any DOM element — no React,
+ * Vue, or Angular required. Mirrors the React `<ChatWidget>`: it streams replies,
+ * renders clickable suggested replies, and installs conversational form collectors.
+ *
+ * Message content is rendered as plain text (no markdown) to stay dependency-free;
+ * use the React `<Message>` component if you need GitHub-flavored markdown.
+ *
+ * ```ts
+ * import { mountChatWidget } from "@useago/sdk/widget";
+ *
+ * const widget = mountChatWidget("#chat", {
+ *   config: { baseUrl: "https://YOUR-DOMAIN.useago.com" },
+ *   title: "Book a demo",
+ *   forms: [{
+ *     name: "demo_request",
+ *     description: "A request to book a product demo.",
+ *     schema: {
+ *       type: "object",
+ *       properties: { name: { type: "string" }, email: { type: "string" } },
+ *       required: ["name", "email"],
+ *     },
+ *     submit: { via: "backend", destination: "demo_webhook" },
+ *   }],
+ * });
+ * // later: widget.destroy();
+ * ```
+ */
+export declare function mountChatWidget(target: string | HTMLElement, options: MountChatWidgetOptions): ChatWidgetHandle;
+
+/**
+ * Options for {@link mountChatWidget} — the framework-agnostic (pure TS/JS)
+ * equivalent of the React `<ChatWidget>` component. Same features: conversational
+ * forms (form creator) and clickable suggested replies.
+ */
+export declare interface MountChatWidgetOptions {
+    /** An existing AGO client. Provide this OR `config`. */
+    client?: AgoClient;
+    /** Config to build a client when `client` is not supplied. `baseUrl` is required. */
+    config?: AgoConfig;
+    /** Initial conversation ID to continue. */
+    conversationId?: string;
+    /**
+     * Resume the visitor's last active thread across reloads. `true` enables defaults
+     * (localStorage, widget id under `ago_widget_id`); pass an object to set `storage`
+     * (e.g. `sessionStorage`), `key`, or an explicit `widgetId`. Built on
+     * {@link createConversationSession}: the visitor is identified by a single stable
+     * widget id and the backend hands back their most recently updated conversation.
+     * An explicit `conversationId` still wins as the initial thread. Off by default.
+     */
+    persistConversation?: boolean | Partial<ConversationSessionOptions>;
+    /** Widget title shown in the header. */
+    title?: string;
+    /** Message shown before any conversation has started. */
+    welcomeMessage?: string;
+    /** Input placeholder. */
+    placeholder?: string;
+    /** Enable file attachments. */
+    allowFiles?: boolean;
+    /** Widget height (number → px). */
+    height?: string | number;
+    /** URL of a logo shown in the header. */
+    logoUrl?: string;
+    /** Show the agent name above assistant messages. Defaults to `false`. */
+    showAgentName?: boolean;
+    /**
+     * Load the visitor's conversation list into `widget.threads` on mount and refresh
+     * it after each turn (one `GET /conversations` per load). Off by default to avoid
+     * the request when the integrator doesn't need it; `widget.refreshThreads()` stays
+     * callable on demand regardless.
+     */
+    loadThreads?: boolean;
+    /**
+     * Conversational forms the agent can fill and submit during the chat. Each
+     * config is installed as a {@link createFormCollector} for the lifetime of the
+     * widget (removed on `destroy()`).
+     */
+    forms?: CreateFormCollectorOptions[];
+    /**
+     * How clicking a suggested follow-up reply behaves. Defaults to sending the
+     * reply as a new user message. Pass a handler to override, or `false` to
+     * render the suggestions as non-interactive.
+     */
+    onFollowUpClick?: ((reply: string) => void) | false;
+    /** Called when the user sends a message. */
+    onMessageSent?: (content: string) => void;
+    /** Called when an assistant message completes. */
+    onMessageReceived?: (message: {
+        id: string;
+        content: string;
+    }) => void;
+}
+
+/**
+ * Options for sending a message
+ */
+declare interface SendMessageOptions {
+    /** Existing conversation ID */
+    conversationId?: string;
+    /** Override default agent */
+    agentId?: string;
+    /** File attachments */
+    files?: File[];
+}
+
+/** The slice of the Web Storage API that {@link createStore} relies on. */
+declare type StorageLike = Pick<Storage, "getItem" | "setItem">;
+
+/**
+ * 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.
+ */
+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;
+
+/**
+ * Tool call data from SSE stream
+ */
+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>;
+}
+
+declare type ToolCallType = "form" | "confirmation_input" | "status_message" | "progress_indicator" | "client_function" | "reasoning" | "mcp_ui_resource";
+
 export { }