@useago/sdk 0.4.7 → 1.0.0

package/dist/testing.d.cts

@@ -0,0 +1,482 @@
+/**
+ * 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;
+    /**
+     * Broadcast that the client-side context changed by emitting `context:changed`
+     * with the fresh snapshot. The context-mutating methods call this automatically;
+     * stateful helpers whose context lives in a store (e.g. `createFormCollector`)
+     * call it when their store updates so observers like the dev panel stay live.
+     */
+    notifyContextChanged(): void;
+    /**
+     * 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 {
+    /**
+     * The client-side context changed: a context entry or dynamic provider was
+     * added/removed, or a stateful helper (e.g. `createFormCollector`) updated its
+     * store. Carries the fresh snapshot so observers — notably the dev panel — can
+     * repaint without waiting for the next message. Fires for the form collector's
+     * initial install too, so its missing fields show from the start of a conversation.
+     */
+    "context:changed": ContextSnapshot | null;
+    "message:start": {
+        conversationId: string;
+        messageId: string;
+    };
+    "message:chunk": {
+        content: string;
+        conversationId: string;
+        messageId: string;
+    };
+    /**
+     * The main answer text is done (backend emitted `status: "DONE"`), but follow-up
+     * replies may still be pending. Fires once, before `message:complete`.
+     */
+    "message:answer-complete": AgoMessage;
+    "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;
+}
+
+/**
+ * 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[];
+}
+
+/**
+ * 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;
+
+/**
+ * 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;
+
+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";
+
+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;
+
+/**
+ * Options for sending a message
+ */
+declare interface SendMessageOptions {
+    /** Existing conversation ID */
+    conversationId?: string;
+    /** Override default agent */
+    agentId?: string;
+    /** File attachments */
+    files?: File[];
+}
+
+/**
+ * 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 { }