@useago/sdk 1.7.1 → 1.9.0

package/dist/index.d.ts

@@ -312,9 +312,40 @@ export declare class AgoClient {
      */
     submitFormCollector(name: string, values: Record<string, unknown>): Promise<unknown>;
     /**
-     * Submit feedback for a message
+     * Report an answer: thumbs up/down, optionally with what went wrong.
+     *
+     * ```ts
+     * await client.submitFeedback(message.id, "negative", {
+     *   reasons: ["inaccurate"],
+     *   comment: "The price it quoted is from last year.",
+     * });
+     * ```
+     *
+     * A bare rating is a reaction (the thumbs counted in the dashboard). Adding a
+     * reason or a comment also files it in the feedback list, the analytics and
+     * the CSV export, so someone can act on it.
+     */
+    submitFeedback(messageId: string, rating: FeedbackRating, details?: FeedbackDetails): Promise<void>;
+    /**
+     * Report a whole conversation ("this chat is not working").
+     *
+     * ```ts
+     * await client.submitConversationFeedback(conversationId, "negative", {
+     *   reasons: ["information_not_found"],
+     *   comment: "It never answered my question.",
+     * });
+     * ```
+     *
+     * Feedback is stored per message, so this attaches the report to the last
+     * answer of the conversation, which is the one the user is reacting to.
+     * Returns the message id it landed on.
+     *
+     * Pass `lastMessageId` when you already have it (the widget does) to skip the
+     * lookup round-trip.
      */
-    submitFeedback(messageId: string, rating: "positive" | "negative"): Promise<void>;
+    submitConversationFeedback(conversationId: string, rating: FeedbackRating, details?: FeedbackDetails & {
+        lastMessageId?: string;
+    }): Promise<string>;
     /**
      * Register a client-side function that AGO can call.
      * Accepts either a definition object or (name, handler, schema) args.
@@ -919,6 +950,14 @@ export declare interface AgoPageDataSource<T = unknown> {
     maxResultBytes?: number;
 }
 
+/** The verdict part of a setPageState answer, without the page snapshot. */
+export declare interface AgoPageStateEnvelope {
+    success: boolean;
+    applied: string[];
+    unchanged: string[];
+    rejected?: Record<string, string>;
+}
+
 /**
  * Options for {@link AgoClient.registerPageStateFunction}.
  */
@@ -949,6 +988,15 @@ export declare interface AgoPageStateOptions {
     settleTimeoutMs?: number;
 }
 
+/**
+ * What `setPageState` answers the agent. Every non-dropped field the agent sent
+ * is accounted for by name, so it can tell a change it made from one that was
+ * already true. Dropped placeholders are intentionally omitted.
+ */
+export declare interface AgoPageStateResult<TData = unknown> extends AgoPageStateEnvelope {
+    data?: TData;
+}
+
 /**
  * Knowledge source citation
  */
@@ -978,12 +1026,27 @@ export declare interface AgoStateControl<T = unknown> {
             enum?: (string | number)[];
         };
     };
+    /** String-only: `""` means "clear" instead of being dropped as filler. */
+    clearable?: boolean;
     /** Current value → pushed as dynamic context so the agent knows what to change. */
     get?: () => T;
     /** Apply the state change on the page. May be async. */
-    set: (value: T) => void | Promise<void>;
+    set: (value: T) => void | AgoStateSetResult | Promise<void | AgoStateSetResult>;
 }
 
+/**
+ * Tagged outcome a page setter may return to reject or mark unchanged.
+ *
+ * Returning nothing (void) means APPLY. Returning an unrecognized JS value
+ * (e.g. a string from an assignment expression) is also treated as APPLY.
+ */
+export declare type AgoStateSetResult = {
+    result: "rejected";
+    reason: string;
+} | {
+    result: "unchanged";
+};
+
 /**
  * SSE stream error
  *
@@ -1564,6 +1627,40 @@ export declare class EventEmitter<Events extends Record<string, any> = Record<st
 
 declare type EventHandler<T = unknown> = (data: T) => void;
 
+/** The four values of {@link FeedbackReason}, in dashboard order. */
+export declare const FEEDBACK_REASONS: readonly FeedbackReason[];
+
+/**
+ * Why the user is reporting a message (see `AgoClient.submitFeedback`).
+ *
+ * A rating on its own is a reaction (the thumbs count). Add a reason or a
+ * comment and the report also lands in the feedback dashboard, the analytics
+ * and the CSV export, where someone can act on it.
+ */
+export declare interface FeedbackDetails {
+    /** What went wrong. Several can apply at once. */
+    reasons?: FeedbackReason[];
+    /** The user's own words. Trimmed server-side; 5000 characters max. */
+    comment?: string;
+}
+
+/** Thumbs up / thumbs down on an answer. */
+export declare type FeedbackRating = "positive" | "negative";
+
+/**
+ * What went wrong with an answer. These are the four buckets the AGO feedback
+ * dashboard filters and charts on.
+ */
+export declare type FeedbackReason = 
+/** The answer states something false. */
+"inaccurate"
+/** The answer is right but stops short. */
+| "incomplete"
+/** The agent could not find the information. */
+| "information_not_found"
+/** Something broke: the widget, a tool call, the stream. */
+| "technical_issue";
+
 /** Human-readable file size (e.g. "12.3 KB"). Empty string when size is unknown. */
 export declare function formatFileSize(bytes?: number): string;
 

package/dist/index.js

@@ -1,43 +1,44 @@
-import { a as w, c as C, d as y, f as S, i as E, l as b, m as v, o as F, p as T, r as I, s as M, t as U, u as _ } from "./functions-tzyOZNp6.js";
-import { C as L, S as N, T as x, _ as D, a as G, b as c, c as O, d as R, f as q, g as P, h as H, l as J, m as j, n as z, o as B, p as V, r as W, s as X, t as p, u as Y, v as $, w as K, x as Q, y as Z } from "./AgoClient-BJjLTOw4.js";
-import { t as oe } from "./autoContinue-CC8K9mBU.js";
-import { t as re } from "./createConversationSession-Bgvx753t.js";
-import { n as ne, r as se, t as ie } from "./createFormCollector-CM3qjGcM.js";
-import { t as ge } from "./createMockClient-BDLW6tVc.js";
+import { a as w, c as C, d as E, f as y, i as S, l as b, m as v, o as F, p as I, r as M, s as T, t as _, u as U } from "./functions-tzyOZNp6.js";
+import { _ as N, b as D, c as L, d as O, f as R, g as x, h as G, i as q, l as P, m as B, n as c, o as H, p as J, r as j, s as z, t as K, u as V, v as W, x as X, y as Y } from "./types-CPga11Of.js";
+import { a as Q, i as Z, n as p, r as ee, t as oe } from "./errors-BLfjXnLB.js";
+import { t as re } from "./autoContinue-CC8K9mBU.js";
+import { t as ne } from "./createConversationSession-BaaXBQ5b.js";
+import { n as ie, r as ue, t as ge } from "./createFormCollector-Cf7kGhCB.js";
+import { t as fe } from "./createMockClient-5YF-ZbVu.js";
 import "./testing.js";
-function me(e) {
+function de(e) {
   return e;
 }
-function le(e, o) {
+function ce(e, o) {
   return e.on("message:complete", o), () => e.off("message:complete", o);
 }
-function de(e, o) {
+function pe(e, o) {
   return e.on("message:chunk", o), () => e.off("message:chunk", o);
 }
-function ce(e, o) {
+function Ae(e, o) {
   return e.on("message:start", o), () => e.off("message:start", o);
 }
-function pe(e, o) {
+function he(e, o) {
   return e.on("message:error", o), () => e.off("message:error", o);
 }
-function Ae(e, o) {
+function we(e, o) {
   return e.on("toolCall:received", o), () => e.off("toolCall:received", o);
 }
-function he(e, o) {
+function Ce(e, o) {
   return e.on("form:submitted", o), () => e.off("form:submitted", o);
 }
-function we(e, o) {
+function Ee(e, o) {
   return e.on("form:error", o), () => e.off("form:error", o);
 }
-function Ce(e, o) {
+function ye(e, o) {
   return e.on("function:invoke", o), () => e.off("function:invoke", o);
 }
-async function* ye(e, o, u) {
+async function* Se(e, o, u) {
   const n = [];
   let r = null, a = !1;
   const g = (s) => {
     n.push(s), r?.();
-  }, f = (s) => g({
+  }, m = (s) => g({
     type: "start",
     data: s
   }), t = (s) => g({
@@ -48,7 +49,7 @@ async function* ye(e, o, u) {
       type: "complete",
       data: s
     }), a = !0, r?.();
-  }, m = (s) => {
+  }, f = (s) => {
     g({
       type: "error",
       data: s
@@ -59,7 +60,7 @@ async function* ye(e, o, u) {
   }), d = () => {
     a = !0, r?.();
   };
-  e.on("message:start", f), e.on("message:chunk", t), e.on("message:complete", i), e.on("message:error", m), e.on("message:stopped", d), e.on("toolCall:received", l), e.sendMessage(o, u).catch(() => {
+  e.on("message:start", m), e.on("message:chunk", t), e.on("message:complete", i), e.on("message:error", f), e.on("message:stopped", d), e.on("toolCall:received", l), e.sendMessage(o, u).catch(() => {
     a = !0, r?.();
   });
   try {
@@ -67,7 +68,7 @@ async function* ye(e, o, u) {
       r = s;
     }), r = null);
   } finally {
-    e.off("message:start", f), e.off("message:chunk", t), e.off("message:complete", i), e.off("message:error", m), e.off("message:stopped", d), e.off("toolCall:received", l);
+    e.off("message:start", m), e.off("message:chunk", t), e.off("message:complete", i), e.off("message:error", f), e.off("message:stopped", d), e.off("toolCall:received", l);
   }
 }
 function A(e) {
@@ -86,7 +87,7 @@ function A(e) {
       i && (o = o || i.getAttribute("data-ago-base-url") || void 0, u = u || i.getAttribute("data-ago-widget-id") || void 0, n = n || i.getAttribute("data-ago-agent") || i.getAttribute("data-ago-agent-id") || void 0, r = r || i.getAttribute("data-ago-permission") || void 0, a = a || i.getAttribute("data-ago-user-email") || void 0);
   }
   o = e?.baseUrl || o, u = e?.widgetId || u, n = e?.agent || e?.defaultAgentId || n, r = e?.permission || r, a = e?.userEmail || a, g = e?.userJwt || g;
-  const f = e?.debug;
+  const m = e?.debug;
   return o ? {
     baseUrl: o,
     widgetId: u,
@@ -94,75 +95,76 @@ function A(e) {
     permission: r,
     userEmail: a,
     userJwt: g,
-    debug: f
+    debug: m
   } : null;
 }
-function Se(e) {
+function be(e) {
   const o = A(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 p(o);
+  if (!o) throw new p('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 c(o);
 }
-function Ee(e, o) {
+function ve(e, o) {
   return {
     ...e,
     handler: o
   };
 }
 export {
-  K as ActivityLedger,
-  Z as AgoApiError,
-  p as AgoClient,
-  c as AgoError,
-  Q as AgoFunctionError,
-  N as AgoNetworkError,
-  L as AgoStreamError,
-  Y as ClientContextRegistry,
-  x as DEFAULT_MAX_ACTIVITY_ENTRIES,
-  W as EventEmitter,
-  D as FunctionRegistry,
-  O as SSEHandler,
-  P as SignalCollector,
-  oe as attachAutoContinueAfterNavigation,
+  D as ActivityLedger,
+  oe as AgoApiError,
+  c as AgoClient,
+  p as AgoError,
+  ee as AgoFunctionError,
+  Z as AgoNetworkError,
+  Q as AgoStreamError,
+  O as ClientContextRegistry,
+  X as DEFAULT_MAX_ACTIVITY_ENTRIES,
+  q as EventEmitter,
+  K as FEEDBACK_REASONS,
+  W as FunctionRegistry,
+  P as SSEHandler,
+  N as SignalCollector,
+  re as attachAutoContinueAfterNavigation,
   A as autoDetectConfig,
-  G as canInlineImage,
-  U as copyToClipboard,
-  Se as createAgo,
+  H as canInlineImage,
+  _ as copyToClipboard,
+  be as createAgo,
   R as createAgoProactive,
-  re as createConversationSession,
-  ie as createFormCollector,
-  ye as createMessageStream,
-  ge as createMockClient,
-  H as createStore,
-  me as defineFunction,
-  ne as deriveFormStatus,
-  B as formatFileSize,
-  I as getLocalStorage,
-  E as getUserLocation,
+  ne as createConversationSession,
+  ge as createFormCollector,
+  Se as createMessageStream,
+  fe as createMockClient,
+  x as createStore,
+  de as defineFunction,
+  ie as deriveFormStatus,
+  z as formatFileSize,
+  M as getLocalStorage,
+  S as getUserLocation,
   w as highlightElement,
-  J as isStreamNetworkError,
-  se as loadFormCollector,
-  $ as logger,
-  q as matchesRoutePattern,
-  V as matchesWhen,
-  we as onFormError,
-  he as onFormSubmitted,
-  Ce as onFunctionInvoke,
-  le as onMessage,
-  de as onMessageChunk,
-  pe as onMessageError,
-  ce as onMessageStart,
-  Ae as onToolCall,
+  V as isStreamNetworkError,
+  ue as loadFormCollector,
+  Y as logger,
+  J as matchesRoutePattern,
+  B as matchesWhen,
+  Ee as onFormError,
+  Ce as onFormSubmitted,
+  ye as onFunctionInvoke,
+  ce as onMessage,
+  pe as onMessageChunk,
+  he as onMessageError,
+  Ae as onMessageStart,
+  we as onToolCall,
   F as openUrl,
-  j as partialDeepMatch,
-  X as safeAttachmentUrl,
-  M as scrollToElement,
+  G as partialDeepMatch,
+  L as safeAttachmentUrl,
+  T as scrollToElement,
   C as setLocalStorage,
   b as setTheme,
-  _ as showConfirmDialog,
-  y as showNotification,
-  S as showToast,
-  T as submitForm,
+  U as showConfirmDialog,
+  E as showNotification,
+  y as showToast,
+  I as submitForm,
   v as trackEvent,
-  z as validateConfig,
-  Ee as withHandler
+  j as validateConfig,
+  ve as withHandler
 };