@useago/sdk 1.7.1 → 1.9.0

package/dist/react.d.ts

@@ -330,9 +330,40 @@ 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: "positive" | "negative"): Promise<void>;
+    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.
+     */
+    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.
@@ -1048,12 +1079,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.
+ */
+declare type AgoStateSetResult = {
+    result: "rejected";
+    reason: string;
+} | {
+    result: "unchanged";
+};
+
 /**
  * Chat input component with send button
  */
@@ -1133,6 +1179,17 @@ export declare interface ChatWidgetProps {
      * fetch the definition from the backend ({@link loadFormCollector}).
      */
     forms?: Array<CreateFormCollectorOptions | LoadFormCollectorOptions>;
+    /**
+     * Let the user report an answer that did not work: thumbs under each finished
+     * answer, and after a thumbs-down a panel to say what went wrong. Off by
+     * default. `true` uses the English labels; pass the `<MessageFeedback>` props
+     * to translate the strings or observe what was sent.
+     *
+     * ```tsx
+     * <ChatWidget feedback />
+     * ```
+     */
+    feedback?: boolean | Omit<MessageFeedbackProps, "messageId" | "client">;
     /**
      * How clicking a suggested follow-up reply behaves. Defaults to sending the
      * reply as a new user message. Pass a handler to override, or `false` to
@@ -1377,6 +1434,8 @@ export declare interface CreateFormCollectorOptions<V = Record<string, unknown>>
  */
 export declare function createMockClient(options?: MockAgoClientOptions): MockAgoClient;
 
+export declare const DEFAULT_MESSAGE_FEEDBACK_LABELS: MessageFeedbackLabels;
+
 /**
  * Compute which required fields are still empty and whether the form is complete.
  * Pure — the single home for the "required + non-empty" rule, shared by the update
@@ -1404,6 +1463,40 @@ declare interface ElementProps {
     attrs: Record<string, string | null>;
 }
 
+/** 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";
+
 export declare interface FormCollector<V = Record<string, unknown>> {
     name: string;
     /** Observable store driving the form UI (read via `useAgoStore`). */
@@ -1656,6 +1749,60 @@ export declare interface MarkdownProps {
 
 export declare const Message: default_2.FC<MessageProps>;
 
+/**
+ * Thumbs under an answer, and a "what went wrong?" panel after a thumbs-down.
+ *
+ * ```tsx
+ * <MessageFeedback messageId={message.id} />
+ * ```
+ *
+ * The thumb is sent as soon as it is clicked, so the signal survives a user who
+ * ignores the panel; sending the panel then files the detailed report (reasons
+ * and comment), which is what shows up in the AGO feedback dashboard.
+ */
+export declare const MessageFeedback: default_2.FC<MessageFeedbackProps>;
+
+/** Every string the feedback row shows, so a non-English app can translate it. */
+export declare interface MessageFeedbackLabels {
+    helpful: string;
+    notHelpful: string;
+    whatWentWrong: string;
+    reasons: Record<FeedbackReason, string>;
+    commentPlaceholder: string;
+    send: string;
+    thanks: string;
+}
+
+export declare interface MessageFeedbackProps {
+    /** The answer being judged. */
+    messageId: string;
+    /** The AGO client. If omitted, reads from AgoProvider context. */
+    client?: AgoClient;
+    /**
+     * After a thumbs-down, open the panel asking what went wrong. Defaults to
+     * `true`; pass `false` to collect thumbs only.
+     */
+    askWhy?: boolean;
+    /** Override any of the strings (reason labels can be overridden one by one). */
+    labels?: Partial<Omit<MessageFeedbackLabels, "reasons">> & {
+        reasons?: Partial<Record<FeedbackReason, string>>;
+    };
+    /**
+     * Called after a report was accepted by the API. Fires once per accepted
+     * report, so a thumbs-down followed by the panel calls it twice: first for
+     * the bare thumb, then for the detailed report.
+     */
+    onSubmit?: (report: {
+        messageId: string;
+        rating: FeedbackRating;
+        reasons: FeedbackReason[];
+        comment?: string;
+    }) => void;
+    /** Called when a report could not be sent. */
+    onError?: (error: Error) => void;
+    className?: string;
+}
+
 export declare interface MessageProps {
     message: AgoMessage;
     className?: string;
@@ -1678,6 +1825,11 @@ export declare interface MessageProps {
      * bubble is then dropped entirely rather than left as a blank box.
      */
     showStreamingDots?: boolean;
+    /**
+     * Rendered under an assistant bubble, above the suggested replies. Meant for
+     * `<MessageFeedback messageId={message.id} />`, but takes any node.
+     */
+    feedback?: default_2.ReactNode;
 }
 
 declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED"
@@ -2545,6 +2697,48 @@ export declare interface UseConversationResult {
     refreshConversations: () => Promise<void>;
 }
 
+/**
+ * Hook to report answers that did not work.
+ *
+ * ```tsx
+ * const { ratings, submitFeedback } = useFeedback();
+ *
+ * <button onClick={() => submitFeedback(message.id, "negative", {
+ *   reasons: ["inaccurate"],
+ * })} aria-pressed={ratings[message.id] === "negative"}>
+ *   👎
+ * </button>
+ * ```
+ *
+ * A bare rating is a reaction. Adding a reason or a comment files the report in
+ * the AGO feedback dashboard, where someone can act on it.
+ */
+export declare function useFeedback({ client: clientProp, }?: UseFeedbackOptions): UseFeedbackResult;
+
+export declare interface UseFeedbackOptions {
+    /** The AGO client instance. If omitted, reads from AgoProvider context. */
+    client?: AgoClient;
+}
+
+export declare interface UseFeedbackResult {
+    /**
+     * The rating already sent for each message, keyed by message id. Use it to
+     * light up the thumb the user picked (and to re-render after a change of
+     * mind: sending a new rating overwrites the previous one).
+     */
+    ratings: Record<string, FeedbackRating>;
+    /** Report one answer. */
+    submitFeedback: (messageId: string, rating: FeedbackRating, details?: FeedbackDetails) => Promise<void>;
+    /** Report the conversation; lands on its last answer, whose id is returned. */
+    submitConversationFeedback: (conversationId: string, rating: FeedbackRating, details?: FeedbackDetails & {
+        lastMessageId?: string;
+    }) => Promise<string>;
+    /** True while a report is in flight. */
+    isSubmitting: boolean;
+    /** The last failure, or null. Cleared when a new report starts. */
+    error: Error | null;
+}
+
 /**
  * React wiring for {@link createFormCollector}: registers the collector's client
  * functions + dynamic context on mount, removes them on unmount, and returns the