@useago/sdk 1.0.1 → 1.0.2

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
@@ -205,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;
     /**
@@ -240,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;
     };
@@ -270,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;
@@ -284,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;
@@ -343,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);
 }
 
 /**
@@ -623,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
@@ -1361,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.js

@@ -1,7 +1,7 @@
-import { a as w, c as h, d as A, f as y, i as C, l as E, n as S, o as b, r as v, s as k, t as d, u as F } from "./AgoClient-CZYNL25R.js";
-import { i as T, n as I, r as U, t as G } from "./createFormCollector-Bk0DRhUf.js";
-import { t as q } from "./createConversationSession-Bmqj2rSS.js";
-import { t as L } from "./createMockClient-DwdxNwEn.js";
+import { a as h, c as A, d as y, f as C, i as E, l as b, n as S, o as v, p as k, r as F, s as M, t as d, u as c } from "./AgoClient-bQozE6-A.js";
+import { i as I, n as U, r as G, t as O } from "./createFormCollector-D-TpSd9x.js";
+import { t as x } from "./createConversationSession-BbK3ou1k.js";
+import { t as N } from "./createMockClient-DwdxNwEn.js";
 import "./testing.js";
 import { a as H, c as J, d as R, f as j, i as B, l as P, m as $, o as z, p as K, r as Q, s as V, t as W, u as X } from "./functions-C1-5vadY.js";
 function Y(e) {
@@ -10,26 +10,26 @@ function Y(e) {
 function Z(e, o) {
   return e.on("message:complete", o), () => e.off("message:complete", o);
 }
-function _(e, o) {
+function ee(e, o) {
   return e.on("message:chunk", o), () => e.off("message:chunk", o);
 }
-function ee(e, o) {
+function oe(e, o) {
   return e.on("message:start", o), () => e.off("message:start", o);
 }
-function oe(e, o) {
+function te(e, o) {
   return e.on("message:error", o), () => e.off("message:error", o);
 }
-function te(e, o) {
+function ae(e, o) {
   return e.on("toolCall:received", o), () => e.off("toolCall:received", o);
 }
 function re(e, o) {
   return e.on("function:invoke", o), () => e.off("function:invoke", o);
 }
-async function* ae(e, o, g) {
-  const a = [];
-  let r = null, n = !1;
+async function* ne(e, o, g) {
+  const r = [];
+  let a = null, n = !1;
   const u = (s) => {
-    a.push(s), r?.();
+    r.push(s), a?.();
   }, f = (s) => u({
     type: "start",
     data: s
@@ -40,98 +40,98 @@ async function* ae(e, o, g) {
     u({
       type: "complete",
       data: s
-    }), n = !0, r?.();
-  }, m = (s) => {
+    }), n = !0, a?.();
+  }, l = (s) => {
     u({
       type: "error",
       data: s
-    }), n = !0, r?.();
-  }, l = (s) => u({
+    }), n = !0, a?.();
+  }, m = (s) => u({
     type: "toolCall",
     data: s
   });
-  e.on("message:start", f), e.on("message:chunk", t), e.on("message:complete", i), e.on("message:error", m), e.on("toolCall:received", l), e.sendMessage(o, g).catch(() => {
-    n = !0, r?.();
+  e.on("message:start", f), e.on("message:chunk", t), e.on("message:complete", i), e.on("message:error", l), e.on("toolCall:received", m), e.sendMessage(o, g).catch(() => {
+    n = !0, a?.();
   });
   try {
-    for (; !n || a.length > 0; ) a.length > 0 ? yield a.shift() : (await new Promise((s) => {
-      r = s;
-    }), r = null);
+    for (; !n || r.length > 0; ) r.length > 0 ? yield r.shift() : (await new Promise((s) => {
+      a = s;
+    }), a = null);
   } finally {
-    e.off("message:start", f), e.off("message:chunk", t), e.off("message:complete", i), e.off("message:error", m), e.off("toolCall:received", l);
+    e.off("message:start", f), e.off("message:chunk", t), e.off("message:complete", i), e.off("message:error", l), e.off("toolCall:received", m);
   }
 }
-function c(e) {
-  let o, g, a, r, n, u;
+function p(e) {
+  let o, g, r, a, n, u;
   if (typeof window < "u" && window.AGO) {
     const t = window.AGO;
-    o = t.basepath, g = t.widgetId, a = t.agent || t.defaultAgent, r = t.permission, n = t.email, u = t.jwt;
+    o = t.basepath, g = t.widgetId, r = t.agent || t.defaultAgent, a = t.permission, n = t.email, u = t.jwt;
   }
   if (typeof document < "u") {
     const t = (i) => document.querySelector(`meta[name="${i}"]`)?.getAttribute("content") || void 0;
-    o = o || t("ago-base-url"), g = g || t("ago-widget-id"), a = a || t("ago-agent") || t("ago-agent-id"), r = r || t("ago-permission"), n = n || t("ago-user-email");
+    o = o || t("ago-base-url"), g = g || t("ago-widget-id"), r = r || t("ago-agent") || t("ago-agent-id"), a = a || t("ago-permission"), n = n || t("ago-user-email");
   }
   if (typeof document < "u") {
     const t = [document.body, ...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);
     for (const i of t)
-      i && (o = o || i.getAttribute("data-ago-base-url") || void 0, g = g || i.getAttribute("data-ago-widget-id") || void 0, a = a || i.getAttribute("data-ago-agent") || i.getAttribute("data-ago-agent-id") || void 0, r = r || i.getAttribute("data-ago-permission") || void 0, n = n || i.getAttribute("data-ago-user-email") || void 0);
+      i && (o = o || i.getAttribute("data-ago-base-url") || void 0, g = g || i.getAttribute("data-ago-widget-id") || void 0, r = r || i.getAttribute("data-ago-agent") || i.getAttribute("data-ago-agent-id") || void 0, a = a || i.getAttribute("data-ago-permission") || void 0, n = n || i.getAttribute("data-ago-user-email") || void 0);
   }
-  o = e?.baseUrl || o, g = e?.widgetId || g, a = e?.agent || e?.defaultAgentId || a, r = e?.permission || r, n = e?.userEmail || n, u = e?.userJwt || u;
+  o = e?.baseUrl || o, g = e?.widgetId || g, r = e?.agent || e?.defaultAgentId || r, a = e?.permission || a, n = e?.userEmail || n, u = e?.userJwt || u;
   const f = e?.debug;
   return o ? {
     baseUrl: o,
     widgetId: g,
-    agent: a,
-    permission: r,
+    agent: r,
+    permission: a,
     userEmail: n,
     userJwt: u,
     debug: f
   } : null;
 }
-function ne(e) {
-  const o = c(e);
-  if (!o) throw new Error('createAgo(): could not detect AGO configuration. Set window.AGO, add <meta name="ago-base-url">, or pass { baseUrl } explicitly.');
+function se(e) {
+  const o = p(e);
+  if (!o) throw new c('createAgo(): could not detect AGO configuration. Set window.AGO, add <meta name="ago-base-url">, or pass { baseUrl } explicitly.', "config_missing_base_url");
   return new d(o);
 }
-function se(e, o) {
+function ie(e, o) {
   return {
     ...e,
     handler: o
   };
 }
 export {
-  h as AgoApiError,
+  b as AgoApiError,
   d as AgoClient,
-  E as AgoError,
-  F as AgoFunctionError,
-  A as AgoNetworkError,
-  y as AgoStreamError,
-  w as ClientContextRegistry,
-  S as EventEmitter,
-  b as FunctionRegistry,
-  v as SSEHandler,
-  c as autoDetectConfig,
+  c as AgoError,
+  y as AgoFunctionError,
+  C as AgoNetworkError,
+  k as AgoStreamError,
+  v as ClientContextRegistry,
+  F as EventEmitter,
+  M as FunctionRegistry,
+  E as SSEHandler,
+  p as autoDetectConfig,
   W as copyToClipboard,
-  ne as createAgo,
-  q as createConversationSession,
-  G as createFormCollector,
-  ae as createMessageStream,
-  L as createMockClient,
-  T as createStore,
+  se as createAgo,
+  x as createConversationSession,
+  O as createFormCollector,
+  ne as createMessageStream,
+  N as createMockClient,
+  I as createStore,
   Y as defineFunction,
-  I as deriveFormStatus,
+  U as deriveFormStatus,
   Q as getLocalStorage,
   B as getUserLocation,
   H as highlightElement,
-  C as isStreamNetworkError,
-  U as loadFormCollector,
-  k as logger,
+  h as isStreamNetworkError,
+  G as loadFormCollector,
+  A as logger,
   re as onFunctionInvoke,
   Z as onMessage,
-  _ as onMessageChunk,
-  oe as onMessageError,
-  ee as onMessageStart,
-  te as onToolCall,
+  ee as onMessageChunk,
+  te as onMessageError,
+  oe as onMessageStart,
+  ae as onToolCall,
   z as openUrl,
   V as scrollToElement,
   J as setLocalStorage,
@@ -141,5 +141,6 @@ export {
   j as showToast,
   K as submitForm,
   $ as trackEvent,
-  se as withHandler
+  S as validateConfig,
+  ie as withHandler
 };