@useago/sdk 0.3.4 → 0.4.1

package/dist/widget.d.cts

@@ -31,6 +31,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
      */
@@ -201,6 +207,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;
@@ -313,6 +325,20 @@ export declare interface ChatWidgetHandle {
     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;
 }
@@ -400,6 +426,60 @@ declare interface Conversation {
     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;
@@ -488,6 +568,15 @@ export declare interface MountChatWidgetOptions {
     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. */
@@ -502,6 +591,13 @@ export declare interface MountChatWidgetOptions {
     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
@@ -535,6 +631,9 @@ declare interface SendMessageOptions {
     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

package/dist/widget.d.ts

@@ -31,6 +31,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
      */
@@ -201,6 +207,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;
@@ -313,6 +325,20 @@ export declare interface ChatWidgetHandle {
     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;
 }
@@ -400,6 +426,60 @@ declare interface Conversation {
     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;
@@ -488,6 +568,15 @@ export declare interface MountChatWidgetOptions {
     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. */
@@ -502,6 +591,13 @@ export declare interface MountChatWidgetOptions {
     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
@@ -535,6 +631,9 @@ declare interface SendMessageOptions {
     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