@useago/sdk 1.0.0 → 1.0.2

package/dist/index.d.cts

@@ -27,12 +27,26 @@ export 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
@@ -64,6 +78,13 @@ export declare class AgoClient {
      * Reject a tool call
      */
     rejectToolCall(toolCallId: string): Promise<void>;
+    /**
+     * Fetch a backend-stored form collector definition by name (the single source
+     * of truth for the form's description, schema, and submit target). Used by
+     * `loadFormCollector` / the name-only form of `useFormCollector` so the schema
+     * lives in the backend instead of being hardcoded in client code.
+     */
+    getFormCollector(name: string): Promise<FormCollectorDefinition>;
     /**
      * Relay a completed form collector's values to a server-configured destination.
      *
@@ -198,6 +219,11 @@ export 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;
     /**
@@ -233,8 +259,23 @@ export 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;
     };
@@ -263,7 +304,7 @@ export 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;
@@ -277,10 +318,23 @@ 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;
 }
 
 /**
  * Base error class for AGO SDK
+ *
+ * Error convention: every throw carries a stable `code` (snake_case), a
+ * one-line fix hint in the message, and a doc URL/anchor when one exists.
+ * `code` is the compatibility surface — match on it, never on message text,
+ * which may be reworded in any release. The code registry lives in
+ * docs/general/configuration.md#error-codes.
  */
 export declare class AgoError extends Error {
     code: string;
@@ -336,9 +390,14 @@ export declare interface AgoSource {
 
 /**
  * SSE stream error
+ *
+ * `code` distinguishes failure classes without message parsing:
+ * - `stream_no_body`: the response had no streamable body (usually a
+ *   misconfigured endpoint or a proxy stripping the SSE stream)
+ * - `stream_error` (default): the stream failed mid-flight
  */
 export declare class AgoStreamError extends AgoError {
-    constructor(message: string);
+    constructor(message: string, code?: string);
 }
 
 /**
@@ -616,8 +675,8 @@ export declare const copyToClipboard: ClientFunctionDefinition;
 export declare function createAgo(overrides?: Partial<AgoConfig>): AgoClient;
 
 /**
- * Identify a returning visitor with a single, stable widget id — the same model as
- * the frontend's `getOrGenerateWidgetId` — and resume their last active thread.
+ * Identify a returning visitor with a single, stable anon id (one id, generated
+ * once and reused forever) and resume their last active thread.
  *
  * There is no per-agent conversation id: the widget id is the identity, and the last
  * active thread (its id + the time of its last message) is cached locally so resuming
@@ -814,6 +873,22 @@ export declare interface FormCollector<V = Record<string, unknown>> {
     getValues: () => Partial<V>;
     setValues: (patch: Partial<V>) => void;
     reset: () => void;
+    /** Completeness status (`missing`/`complete`) derived from the current values + schema. */
+    getStatus: () => FormCollectorStatus;
+}
+
+/**
+ * The backend-stored shape returned by `GET /api/sdk/v1/forms/{name}` (see
+ * {@link AgoClient.getFormCollector}). Mirrors the persistable subset of
+ * {@link CreateFormCollectorOptions}: the `submit` here is never the client-only
+ * `handler` variant (a function can't be stored server-side).
+ */
+export declare interface FormCollectorDefinition<V = Record<string, unknown>> {
+    name: string;
+    description: string;
+    schema: FormCollectorSchema;
+    /** Server-stored submit target, if any. Absent means collect-only. */
+    submit?: SubmitConfig<V>;
 }
 
 /**
@@ -988,6 +1063,30 @@ export declare const highlightElement: ClientFunctionDefinition;
  */
 export declare function isStreamNetworkError(error: Error): boolean;
 
+/**
+ * Async sibling of {@link createFormCollector} that pulls the form's definition
+ * (description + schema + submit target) from the backend by name — the single
+ * source of truth — instead of hardcoding it in client code. Any field passed in
+ * `options` overrides the fetched one (e.g. a client-only `submit` handler or
+ * `initialValues`).
+ *
+ * ```ts
+ * const order = await loadFormCollector(client, { name: "order" });
+ * order.install(client);
+ * ```
+ */
+export declare function loadFormCollector<V = Record<string, unknown>>(client: Pick<AgoClient, "getFormCollector">, options: LoadFormCollectorOptions<V>): Promise<FormCollector<V>>;
+
+/**
+ * Options for {@link loadFormCollector} / the name-only form of `useFormCollector`:
+ * the `name` is required and the definition is fetched from the backend, while any
+ * field here overrides the fetched one — notably a client-only `submit` handler,
+ * which can't be stored server-side.
+ */
+export declare interface LoadFormCollectorOptions<V = Record<string, unknown>> extends Partial<Omit<CreateFormCollectorOptions<V>, "name">> {
+    name: string;
+}
+
 /**
  * Debug logger for SDK
  */
@@ -1314,6 +1413,29 @@ export declare type ToolCallType = "form" | "confirmation_input" | "status_messa
  */
 export declare const trackEvent: ClientFunctionDefinition;
 
+/**
+ * Validate an AgoConfig at the public API boundary.
+ *
+ * Rules:
+ * - nullish / non-object config, or a missing/empty/non-string `baseUrl`,
+ *   throws `AgoError` with the stable code `config_missing_base_url`.
+ * - Values starting with `/` are allowed (same-origin proxy paths like
+ *   `/ago-proxy` are a supported embed pattern).
+ * - Values with any `scheme://` are allowed.
+ * - Anything else (no scheme, no leading slash, e.g. "ago.api.useago.com")
+ *   warns once per process — it usually means a forgotten protocol. It does
+ *   not throw: the request fails at send time with a runtime-specific error
+ *   (Node: URL parse error; browser: relative fetch), and a hard throw here
+ *   could break embeds we cannot foresee.
+ *
+ * The warning never echoes the configured value: misconfigured baseUrls
+ * sometimes carry credentials (e.g. `https://user:token@host`).
+ *
+ * @param context Prefix for the error message, naming the API the developer
+ *   actually called (e.g. "AgoClient", "createAgo()").
+ */
+export declare function validateConfig(config: unknown, context?: string): asserts config is AgoConfig;
+
 /**
  * Attach a handler to a pre-built function definition.
  *

package/dist/index.d.ts

@@ -27,12 +27,26 @@ export 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
@@ -64,6 +78,13 @@ export declare class AgoClient {
      * Reject a tool call
      */
     rejectToolCall(toolCallId: string): Promise<void>;
+    /**
+     * Fetch a backend-stored form collector definition by name (the single source
+     * of truth for the form's description, schema, and submit target). Used by
+     * `loadFormCollector` / the name-only form of `useFormCollector` so the schema
+     * lives in the backend instead of being hardcoded in client code.
+     */
+    getFormCollector(name: string): Promise<FormCollectorDefinition>;
     /**
      * Relay a completed form collector's values to a server-configured destination.
      *
@@ -198,6 +219,11 @@ export 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;
     /**
@@ -233,8 +259,23 @@ export 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;
     };
@@ -263,7 +304,7 @@ export 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;
@@ -277,10 +318,23 @@ 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;
 }
 
 /**
  * Base error class for AGO SDK
+ *
+ * Error convention: every throw carries a stable `code` (snake_case), a
+ * one-line fix hint in the message, and a doc URL/anchor when one exists.
+ * `code` is the compatibility surface — match on it, never on message text,
+ * which may be reworded in any release. The code registry lives in
+ * docs/general/configuration.md#error-codes.
  */
 export declare class AgoError extends Error {
     code: string;
@@ -336,9 +390,14 @@ export declare interface AgoSource {
 
 /**
  * SSE stream error
+ *
+ * `code` distinguishes failure classes without message parsing:
+ * - `stream_no_body`: the response had no streamable body (usually a
+ *   misconfigured endpoint or a proxy stripping the SSE stream)
+ * - `stream_error` (default): the stream failed mid-flight
  */
 export declare class AgoStreamError extends AgoError {
-    constructor(message: string);
+    constructor(message: string, code?: string);
 }
 
 /**
@@ -616,8 +675,8 @@ export declare const copyToClipboard: ClientFunctionDefinition;
 export declare function createAgo(overrides?: Partial<AgoConfig>): AgoClient;
 
 /**
- * Identify a returning visitor with a single, stable widget id — the same model as
- * the frontend's `getOrGenerateWidgetId` — and resume their last active thread.
+ * Identify a returning visitor with a single, stable anon id (one id, generated
+ * once and reused forever) and resume their last active thread.
  *
  * There is no per-agent conversation id: the widget id is the identity, and the last
  * active thread (its id + the time of its last message) is cached locally so resuming
@@ -814,6 +873,22 @@ export declare interface FormCollector<V = Record<string, unknown>> {
     getValues: () => Partial<V>;
     setValues: (patch: Partial<V>) => void;
     reset: () => void;
+    /** Completeness status (`missing`/`complete`) derived from the current values + schema. */
+    getStatus: () => FormCollectorStatus;
+}
+
+/**
+ * The backend-stored shape returned by `GET /api/sdk/v1/forms/{name}` (see
+ * {@link AgoClient.getFormCollector}). Mirrors the persistable subset of
+ * {@link CreateFormCollectorOptions}: the `submit` here is never the client-only
+ * `handler` variant (a function can't be stored server-side).
+ */
+export declare interface FormCollectorDefinition<V = Record<string, unknown>> {
+    name: string;
+    description: string;
+    schema: FormCollectorSchema;
+    /** Server-stored submit target, if any. Absent means collect-only. */
+    submit?: SubmitConfig<V>;
 }
 
 /**
@@ -988,6 +1063,30 @@ export declare const highlightElement: ClientFunctionDefinition;
  */
 export declare function isStreamNetworkError(error: Error): boolean;
 
+/**
+ * Async sibling of {@link createFormCollector} that pulls the form's definition
+ * (description + schema + submit target) from the backend by name — the single
+ * source of truth — instead of hardcoding it in client code. Any field passed in
+ * `options` overrides the fetched one (e.g. a client-only `submit` handler or
+ * `initialValues`).
+ *
+ * ```ts
+ * const order = await loadFormCollector(client, { name: "order" });
+ * order.install(client);
+ * ```
+ */
+export declare function loadFormCollector<V = Record<string, unknown>>(client: Pick<AgoClient, "getFormCollector">, options: LoadFormCollectorOptions<V>): Promise<FormCollector<V>>;
+
+/**
+ * Options for {@link loadFormCollector} / the name-only form of `useFormCollector`:
+ * the `name` is required and the definition is fetched from the backend, while any
+ * field here overrides the fetched one — notably a client-only `submit` handler,
+ * which can't be stored server-side.
+ */
+export declare interface LoadFormCollectorOptions<V = Record<string, unknown>> extends Partial<Omit<CreateFormCollectorOptions<V>, "name">> {
+    name: string;
+}
+
 /**
  * Debug logger for SDK
  */
@@ -1314,6 +1413,29 @@ export declare type ToolCallType = "form" | "confirmation_input" | "status_messa
  */
 export declare const trackEvent: ClientFunctionDefinition;
 
+/**
+ * Validate an AgoConfig at the public API boundary.
+ *
+ * Rules:
+ * - nullish / non-object config, or a missing/empty/non-string `baseUrl`,
+ *   throws `AgoError` with the stable code `config_missing_base_url`.
+ * - Values starting with `/` are allowed (same-origin proxy paths like
+ *   `/ago-proxy` are a supported embed pattern).
+ * - Values with any `scheme://` are allowed.
+ * - Anything else (no scheme, no leading slash, e.g. "ago.api.useago.com")
+ *   warns once per process — it usually means a forgotten protocol. It does
+ *   not throw: the request fails at send time with a runtime-specific error
+ *   (Node: URL parse error; browser: relative fetch), and a hard throw here
+ *   could break embeds we cannot foresee.
+ *
+ * The warning never echoes the configured value: misconfigured baseUrls
+ * sometimes carry credentials (e.g. `https://user:token@host`).
+ *
+ * @param context Prefix for the error message, naming the API the developer
+ *   actually called (e.g. "AgoClient", "createAgo()").
+ */
+export declare function validateConfig(config: unknown, context?: string): asserts config is AgoConfig;
+
 /**
  * Attach a handler to a pre-built function definition.
  *