@useago/sdk 1.0.1 → 1.0.3

package/dist/react.d.cts

@@ -18,12 +18,26 @@ declare class AgoClient {
     private contextRegistry;
     private eventEmitter;
     private config;
+    /** Conversations already warned about an empty reply (one warning each). */
+    private warnedEmptyConversations;
     constructor(config: AgoConfig);
     /**
      * Send a message and receive a streaming response
      */
     sendMessage(content: string, options?: SendMessageOptions): Promise<AgoMessage>;
     private processSSEResponse;
+    /**
+     * Detect a reply that completed as DONE with no content and no activity —
+     * today's backend answers an unknown `agent` slug with an empty 200, which
+     * otherwise fails silently. Emits `message:empty` (always) and warns on the
+     * console once per conversation (unless `warnOnEmptyReply: false`).
+     *
+     * Deferred with setTimeout(0) so both land AFTER `sendMessage` resolves:
+     * `await client.sendMessage(...)` followed by `client.waitFor("message:empty")`
+     * must not race. TEMPORARY heuristic: remove once the backend returns an
+     * explicit error for unknown agents (see TODOS.md, backend issue).
+     */
+    private maybeFlagEmptyReply;
     private handleClientFunctionInvocation;
     /**
      * Get list of conversations
@@ -66,10 +80,11 @@ declare class AgoClient {
      * 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.
+     * the browser never holds the destination name, URL, or its secret — the backend
+     * resolves the destination from the named form's stored definition and forwards
+     * the values from the server.
      */
-    submitFormCollector(destination: string, values: Record<string, unknown>): Promise<unknown>;
+    submitFormCollector(name: string, values: Record<string, unknown>): Promise<unknown>;
     /**
      * Submit feedback for a message
      */
@@ -196,6 +211,11 @@ declare class AgoClient {
     }): Promise<AgoClientEvents[K]>;
     /**
      * Update client configuration
+     *
+     * Validates the MERGED config before committing: omitting a key (or passing
+     * it as `undefined`, common with spread-built partials) keeps the current
+     * value; an explicit empty/non-string `baseUrl` throws `config_missing_base_url`
+     * and leaves the client unchanged (no half-updated state).
      */
     updateConfig(config: Partial<AgoConfig>): void;
     /**
@@ -231,8 +251,23 @@ declare interface AgoClientEvents {
      */
     "message:answer-complete": AgoMessage;
     "message:complete": AgoMessage;
+    /**
+     * A reply finished as `DONE` with empty content and no tool calls, client
+     * functions, or follow-up replies — usually an unknown `agent` slug (the
+     * backend currently answers those with an empty 200). Fires after
+     * `message:complete` AND after `sendMessage` resolves, so subscribing right
+     * after `await sendMessage(...)` still catches it. `messageId` and
+     * `conversationId` are empty strings when the stream completed without any
+     * message data at all (e.g. a proxy stripped the SSE stream).
+     */
+    "message:empty": {
+        conversationId: string;
+        messageId: string;
+    };
     "message:error": {
         error: string;
+        /** Stable error code (see configuration.md#error-codes) when the failure was an AgoError. */
+        code?: string;
         conversationId?: string;
         messageId?: string;
     };
@@ -261,7 +296,7 @@ declare interface AgoClientEvents {
 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. */
+    /** Per-visitor anonymous ID (X-User-Anon-Id header). Auto-generated if not provided. */
     widgetId?: string;
     /** Default agent (id or slug) for new conversations. Shorthand for `defaultAgentId`. */
     agent?: string;
@@ -275,6 +310,13 @@ export declare interface AgoConfig {
     userJwt?: string;
     /** Enable debug logging */
     debug?: boolean;
+    /**
+     * Warn on the console when a reply completes with empty content and no tool
+     * calls (the usual cause is an unknown `agent` slug, which the backend
+     * currently answers with an empty 200). Default `true`. The `message:empty`
+     * event fires regardless of this setting.
+     */
+    warnOnEmptyReply?: boolean;
 }
 
 /**
@@ -757,12 +799,6 @@ export declare interface MessageProps {
      * render on the last message. Defaults to `false`.
      */
     isLast?: boolean;
-    /**
-     * The main answer is done but its follow-up replies are still being generated.
-     * On the last message this renders the "..." indicator in the follow-up slot
-     * until the suggestions arrive. Defaults to `false`.
-     */
-    isAwaitingFollowUps?: boolean;
     /**
      * Called when the user clicks a suggested follow-up reply. When omitted the
      * follow-up buttons render but are not interactive (backwards-compatible).
@@ -841,8 +877,9 @@ declare interface Store<T> {
  *   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).
+ * - `{ via: "backend" }` — the browser relays the values to the backend, which resolves
+ *   the destination from the form's backend-stored definition (name, URL and secret all
+ *   stay server-side). `destination` is deprecated and ignored.
  * - `false` — collect only, no submit function.
  */
 export declare type SubmitConfig<V = Record<string, unknown>> = string | {
@@ -853,7 +890,7 @@ export declare type SubmitConfig<V = Record<string, unknown>> = string | {
     handler: (values: V) => Promise<unknown> | unknown;
 } | {
     via: "backend";
-    destination: string;
+    destination?: string;
 } | false;
 
 /**
@@ -876,9 +913,18 @@ declare type ToolCallType = "form" | "confirmation_input" | "status_message" | "
 
 /**
  * Hook to create and manage an AgoClient instance
+ *
+ * Pass `null` to skip client creation entirely (used by `AgoProvider` when an
+ * external client is supplied — constructing a throwaway client would waste
+ * resources and fail `baseUrl` validation).
  */
 export declare function useAgo(config: UseAgoOptions): UseAgoResult;
 
+export declare function useAgo(config: UseAgoOptions | null): {
+    client: AgoClient | null;
+    isReady: boolean;
+};
+
 /**
  * Returns the AgoClient from the nearest AgoProvider.
  * Throws if used outside of an AgoProvider.

package/dist/react.d.ts

@@ -18,12 +18,26 @@ declare class AgoClient {
     private contextRegistry;
     private eventEmitter;
     private config;
+    /** Conversations already warned about an empty reply (one warning each). */
+    private warnedEmptyConversations;
     constructor(config: AgoConfig);
     /**
      * Send a message and receive a streaming response
      */
     sendMessage(content: string, options?: SendMessageOptions): Promise<AgoMessage>;
     private processSSEResponse;
+    /**
+     * Detect a reply that completed as DONE with no content and no activity —
+     * today's backend answers an unknown `agent` slug with an empty 200, which
+     * otherwise fails silently. Emits `message:empty` (always) and warns on the
+     * console once per conversation (unless `warnOnEmptyReply: false`).
+     *
+     * Deferred with setTimeout(0) so both land AFTER `sendMessage` resolves:
+     * `await client.sendMessage(...)` followed by `client.waitFor("message:empty")`
+     * must not race. TEMPORARY heuristic: remove once the backend returns an
+     * explicit error for unknown agents (see TODOS.md, backend issue).
+     */
+    private maybeFlagEmptyReply;
     private handleClientFunctionInvocation;
     /**
      * Get list of conversations
@@ -66,10 +80,11 @@ declare class AgoClient {
      * 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.
+     * the browser never holds the destination name, URL, or its secret — the backend
+     * resolves the destination from the named form's stored definition and forwards
+     * the values from the server.
      */
-    submitFormCollector(destination: string, values: Record<string, unknown>): Promise<unknown>;
+    submitFormCollector(name: string, values: Record<string, unknown>): Promise<unknown>;
     /**
      * Submit feedback for a message
      */
@@ -196,6 +211,11 @@ declare class AgoClient {
     }): Promise<AgoClientEvents[K]>;
     /**
      * Update client configuration
+     *
+     * Validates the MERGED config before committing: omitting a key (or passing
+     * it as `undefined`, common with spread-built partials) keeps the current
+     * value; an explicit empty/non-string `baseUrl` throws `config_missing_base_url`
+     * and leaves the client unchanged (no half-updated state).
      */
     updateConfig(config: Partial<AgoConfig>): void;
     /**
@@ -231,8 +251,23 @@ declare interface AgoClientEvents {
      */
     "message:answer-complete": AgoMessage;
     "message:complete": AgoMessage;
+    /**
+     * A reply finished as `DONE` with empty content and no tool calls, client
+     * functions, or follow-up replies — usually an unknown `agent` slug (the
+     * backend currently answers those with an empty 200). Fires after
+     * `message:complete` AND after `sendMessage` resolves, so subscribing right
+     * after `await sendMessage(...)` still catches it. `messageId` and
+     * `conversationId` are empty strings when the stream completed without any
+     * message data at all (e.g. a proxy stripped the SSE stream).
+     */
+    "message:empty": {
+        conversationId: string;
+        messageId: string;
+    };
     "message:error": {
         error: string;
+        /** Stable error code (see configuration.md#error-codes) when the failure was an AgoError. */
+        code?: string;
         conversationId?: string;
         messageId?: string;
     };
@@ -261,7 +296,7 @@ declare interface AgoClientEvents {
 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. */
+    /** Per-visitor anonymous ID (X-User-Anon-Id header). Auto-generated if not provided. */
     widgetId?: string;
     /** Default agent (id or slug) for new conversations. Shorthand for `defaultAgentId`. */
     agent?: string;
@@ -275,6 +310,13 @@ export declare interface AgoConfig {
     userJwt?: string;
     /** Enable debug logging */
     debug?: boolean;
+    /**
+     * Warn on the console when a reply completes with empty content and no tool
+     * calls (the usual cause is an unknown `agent` slug, which the backend
+     * currently answers with an empty 200). Default `true`. The `message:empty`
+     * event fires regardless of this setting.
+     */
+    warnOnEmptyReply?: boolean;
 }
 
 /**
@@ -757,12 +799,6 @@ export declare interface MessageProps {
      * render on the last message. Defaults to `false`.
      */
     isLast?: boolean;
-    /**
-     * The main answer is done but its follow-up replies are still being generated.
-     * On the last message this renders the "..." indicator in the follow-up slot
-     * until the suggestions arrive. Defaults to `false`.
-     */
-    isAwaitingFollowUps?: boolean;
     /**
      * Called when the user clicks a suggested follow-up reply. When omitted the
      * follow-up buttons render but are not interactive (backwards-compatible).
@@ -841,8 +877,9 @@ declare interface Store<T> {
  *   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).
+ * - `{ via: "backend" }` — the browser relays the values to the backend, which resolves
+ *   the destination from the form's backend-stored definition (name, URL and secret all
+ *   stay server-side). `destination` is deprecated and ignored.
  * - `false` — collect only, no submit function.
  */
 export declare type SubmitConfig<V = Record<string, unknown>> = string | {
@@ -853,7 +890,7 @@ export declare type SubmitConfig<V = Record<string, unknown>> = string | {
     handler: (values: V) => Promise<unknown> | unknown;
 } | {
     via: "backend";
-    destination: string;
+    destination?: string;
 } | false;
 
 /**
@@ -876,9 +913,18 @@ declare type ToolCallType = "form" | "confirmation_input" | "status_message" | "
 
 /**
  * Hook to create and manage an AgoClient instance
+ *
+ * Pass `null` to skip client creation entirely (used by `AgoProvider` when an
+ * external client is supplied — constructing a throwaway client would waste
+ * resources and fail `baseUrl` validation).
  */
 export declare function useAgo(config: UseAgoOptions): UseAgoResult;
 
+export declare function useAgo(config: UseAgoOptions | null): {
+    client: AgoClient | null;
+    isReady: boolean;
+};
+
 /**
  * Returns the AgoClient from the nearest AgoProvider.
  * Throws if used outside of an AgoProvider.