@useago/sdk 0.3.3 → 0.4.1

package/dist/react.d.cts

@@ -33,6 +33,12 @@ declare class AgoClient {
      * 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
      */
@@ -203,6 +209,12 @@ declare interface AgoClientEvents {
         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;
@@ -359,8 +371,20 @@ export declare interface ChatWidgetProps {
     height?: string | number;
     /** URL of a logo to display in the header */
     logoUrl?: string;
-    /** Show the agent name above assistant messages. Defaults to `true`. */
+    /** Show the agent name above assistant messages. Defaults to `false`. */
     showAgentName?: boolean;
+    /**
+     * Conversational forms the agent can fill and submit during the chat. Each
+     * config is installed as a {@link createFormCollector} (its `update_<name>` /
+     * `submit_<name>` functions + dynamic context) for the lifetime of the widget.
+     */
+    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;
     /** Additional CSS class */
     className?: string;
     /** Callback when a message is sent */
@@ -455,7 +479,29 @@ export declare interface Conversation {
     messages?: AgoMessage[];
 }
 
-declare interface CreateFormCollectorOptions<V = Record<string, unknown>> {
+/**
+ * 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. */
@@ -488,7 +534,7 @@ export declare function createMockClient(options?: MockAgoClientOptions): MockAg
  */
 declare type DynamicContextProvider = () => ContextEntry | null | undefined;
 
-declare interface FormCollector<V = Record<string, unknown>> {
+export declare interface FormCollector<V = Record<string, unknown>> {
     name: string;
     /** Observable store driving the form UI (read via `useAgoStore`). */
     store: Store<FormCollectorState<V>>;
@@ -500,6 +546,14 @@ declare interface FormCollector<V = Record<string, unknown>> {
     contextProvider: () => ContextEntry;
     /** Register the functions + dynamic context on a client. Returns an uninstall fn. */
     install: (client: AgoClient) => () => void;
+    /**
+     * Rebuild the state by replaying the persisted `update_<name>` / `submit_<name>`
+     * tool-call arguments of a loaded conversation — restoring what the agent had
+     * collected after a page reload. Replays from the initial values, so it is
+     * idempotent. `install` wires this to the client's `conversation:loaded` event,
+     * so a custom front rarely needs to call it directly.
+     */
+    hydrate: (toolCalls: readonly ToolCallData[]) => void;
     /** Submit the form now (e.g. from a UI button). Blocks until required fields are filled. */
     submit: () => Promise<FormSubmitResult>;
     getValues: () => Partial<V>;
@@ -512,10 +566,10 @@ declare interface FormCollector<V = Record<string, unknown>> {
  * `parameters`, so one schema feeds the store, the update function, and the
  * dynamic context with no second type.
  */
-declare type FormCollectorSchema = ClientFunctionSchema["parameters"];
+export declare type FormCollectorSchema = ClientFunctionSchema["parameters"];
 
 /** Live state held in the collector's store. */
-declare interface FormCollectorState<V = Record<string, unknown>> {
+export declare interface FormCollectorState<V = Record<string, unknown>> {
     /** Field values collected so far. */
     values: Partial<V>;
     /** Required field names still empty. */
@@ -544,7 +598,7 @@ declare interface FormSchema {
 }
 
 /** Result returned by `submit()` / the generated `submit_<name>` function. */
-declare interface FormSubmitResult {
+export declare interface FormSubmitResult {
     ok: boolean;
     missing?: string[];
     result?: unknown;
@@ -569,8 +623,13 @@ export declare const Message: default_2.FC<MessageProps>;
 export declare interface MessageProps {
     message: AgoMessage;
     className?: string;
-    /** Show the agent name above assistant messages. Defaults to `true`. */
+    /** Show the agent name above assistant messages. Defaults to `false`. */
     showAgentName?: boolean;
+    /**
+     * Called when the user clicks a suggested follow-up reply. When omitted the
+     * follow-up buttons render but are not interactive (backwards-compatible).
+     */
+    onFollowUpClick?: (reply: string) => void;
 }
 
 declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED";
@@ -648,7 +707,7 @@ declare interface Store<T> {
  *   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 | {
+export declare type SubmitConfig<V = Record<string, unknown>> = string | {
     via: "client";
     url: string;
 } | {

package/dist/react.d.ts

@@ -33,6 +33,12 @@ declare class AgoClient {
      * 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
      */
@@ -203,6 +209,12 @@ declare interface AgoClientEvents {
         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;
@@ -359,8 +371,20 @@ export declare interface ChatWidgetProps {
     height?: string | number;
     /** URL of a logo to display in the header */
     logoUrl?: string;
-    /** Show the agent name above assistant messages. Defaults to `true`. */
+    /** Show the agent name above assistant messages. Defaults to `false`. */
     showAgentName?: boolean;
+    /**
+     * Conversational forms the agent can fill and submit during the chat. Each
+     * config is installed as a {@link createFormCollector} (its `update_<name>` /
+     * `submit_<name>` functions + dynamic context) for the lifetime of the widget.
+     */
+    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;
     /** Additional CSS class */
     className?: string;
     /** Callback when a message is sent */
@@ -455,7 +479,29 @@ export declare interface Conversation {
     messages?: AgoMessage[];
 }
 
-declare interface CreateFormCollectorOptions<V = Record<string, unknown>> {
+/**
+ * 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. */
@@ -488,7 +534,7 @@ export declare function createMockClient(options?: MockAgoClientOptions): MockAg
  */
 declare type DynamicContextProvider = () => ContextEntry | null | undefined;
 
-declare interface FormCollector<V = Record<string, unknown>> {
+export declare interface FormCollector<V = Record<string, unknown>> {
     name: string;
     /** Observable store driving the form UI (read via `useAgoStore`). */
     store: Store<FormCollectorState<V>>;
@@ -500,6 +546,14 @@ declare interface FormCollector<V = Record<string, unknown>> {
     contextProvider: () => ContextEntry;
     /** Register the functions + dynamic context on a client. Returns an uninstall fn. */
     install: (client: AgoClient) => () => void;
+    /**
+     * Rebuild the state by replaying the persisted `update_<name>` / `submit_<name>`
+     * tool-call arguments of a loaded conversation — restoring what the agent had
+     * collected after a page reload. Replays from the initial values, so it is
+     * idempotent. `install` wires this to the client's `conversation:loaded` event,
+     * so a custom front rarely needs to call it directly.
+     */
+    hydrate: (toolCalls: readonly ToolCallData[]) => void;
     /** Submit the form now (e.g. from a UI button). Blocks until required fields are filled. */
     submit: () => Promise<FormSubmitResult>;
     getValues: () => Partial<V>;
@@ -512,10 +566,10 @@ declare interface FormCollector<V = Record<string, unknown>> {
  * `parameters`, so one schema feeds the store, the update function, and the
  * dynamic context with no second type.
  */
-declare type FormCollectorSchema = ClientFunctionSchema["parameters"];
+export declare type FormCollectorSchema = ClientFunctionSchema["parameters"];
 
 /** Live state held in the collector's store. */
-declare interface FormCollectorState<V = Record<string, unknown>> {
+export declare interface FormCollectorState<V = Record<string, unknown>> {
     /** Field values collected so far. */
     values: Partial<V>;
     /** Required field names still empty. */
@@ -544,7 +598,7 @@ declare interface FormSchema {
 }
 
 /** Result returned by `submit()` / the generated `submit_<name>` function. */
-declare interface FormSubmitResult {
+export declare interface FormSubmitResult {
     ok: boolean;
     missing?: string[];
     result?: unknown;
@@ -569,8 +623,13 @@ export declare const Message: default_2.FC<MessageProps>;
 export declare interface MessageProps {
     message: AgoMessage;
     className?: string;
-    /** Show the agent name above assistant messages. Defaults to `true`. */
+    /** Show the agent name above assistant messages. Defaults to `false`. */
     showAgentName?: boolean;
+    /**
+     * Called when the user clicks a suggested follow-up reply. When omitted the
+     * follow-up buttons render but are not interactive (backwards-compatible).
+     */
+    onFollowUpClick?: (reply: string) => void;
 }
 
 declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED";
@@ -648,7 +707,7 @@ declare interface Store<T> {
  *   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 | {
+export declare type SubmitConfig<V = Record<string, unknown>> = string | {
     via: "client";
     url: string;
 } | {