@useago/sdk 1.7.2 → 1.12.0

package/CHANGELOG.md

@@ -5,6 +5,181 @@ All notable changes to `@useago/sdk` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.12.0] - 2026-09-07
+
+### Added
+
+- **User metadata on messages.** Set `metadata` on the client config (or in
+  `window.AGO.metadata`) and the JSON-serializable object rides along with every
+  new message, both JSON and multipart uploads. `sendMessage(text, { metadata })`
+  replaces the defaults for that message, `null` omits the field, and
+  `updateConfig({ metadata })` changes it at runtime. In React, `useAgo`
+  re-applies the `metadata` prop without recreating the client. The API stores
+  it as widget metadata on the user, where field mappings can pull selected
+  values into tickets. It is untrusted browser-supplied context, not a
+  credential.
+- **JavaScript errors as agent context.** Set `errorWatcher: true` (or options)
+  on the client config and the page's recent JS errors ride along with every
+  message as the `errors:recent` context entry: uncaught exceptions with file,
+  line and stack, unhandled promise rejections, `console.error` calls (the
+  method is wrapped, calls through, and is restored on `destroy()`), and
+  errors the app hands over with `client.reportError(error, context?)`.
+  Deduplicated with a `count`, capped at 10, pruned after 10 minutes, messages
+  and stacks truncated. Options `maxErrors`, `maxAgeMs`, `maxStackChars`,
+  `filter`. New client methods `enableErrorWatcher`, `disableErrorWatcher`,
+  `reportError`, `getRecentErrors`, `clearErrors`; new event `error:captured`;
+  new exports `ErrorWatcher`, `CapturedError`, `ErrorWatcherOptions`. Off by
+  default: error messages can carry PII.
+- **`jsErrors` proactive matcher.** Captured errors count as friction on the
+  current route (`SignalsSnapshot.jsErrors`, reset on navigation), so a
+  trigger can nudge right after a crash with `when: { jsErrors: 1 }`. Needs
+  `errorWatcher` on; counts only, the messages stay in `client_context`.
+
+### Fixed
+
+- Ticket attachments become available when the dashboard form configuration
+  finishes loading.
+- Ticket forms now support multiple condition values, nested questions and
+  conditional choices across ticketing providers. Changing a branch clears
+  answers that no longer apply. Required questions are checked before sending,
+  including those not yet revealed.
+- Ticket forms respect option groups and order, fields marked always visible,
+  format validation, priority by request type and dashboard success messages
+  when the API supplies these settings.
+
+## [1.11.0] - 2026-09-04
+
+### Added
+
+- **`loadHomeConfig` on the bubble widget: the home screen from the AGO
+  dashboard.** `mountChatWidget(el, { placement: "bubble", loadHomeConfig: true })`
+  takes the home title, the markdown subtitle and the starter cards from
+  `GET /config` instead of the options, the way the hosted widget does. One
+  request on mount, off the critical path: the panel renders with whatever the
+  options set and re-renders when the config lands, and a failed request leaves
+  the options in place. Each part is replaced only when the dashboard has a
+  value for it, and the header keeps the `title` option. The dashboard's
+  *widget starter* (an opening message the agent sends by itself) fires when the
+  panel is first opened, on a fresh visit only, never over a resumed thread.
+- **`agentId` on `ConversationStarter`.** A starter card can name the agent
+  that answers it. Dashboard starters carry their own.
+- **`SdkPermissionConfig.homePage`.** `AgoClient.getConfig()` now maps the
+  `home_page` block (`title`, `subtitle`, `home_starters`, `widget_starter`)
+  when the backend sends one. A starter card shows its `description` and sends
+  its `initial_message`; one with neither is dropped. New types
+  `SdkHomePageConfig`, `SdkHomeStarter`, `SdkWidgetStarter`.
+
+
+## [1.10.0] - 2026-09-03
+
+### Added
+
+- **`placement: "bubble"` on `mountChatWidget`.** The hosted embed widget
+  without the iframe: a 54px launcher bottom right, a teaser bubble one second
+  after mount, and a 550px panel with a home screen (title, markdown
+  `subtitle`, `conversationStarters` cards), a conversation screen, and a chat
+  history screen with relative times and a "New conversation" pill. Reopens
+  the visitor's most recent thread when its last message is under two hours
+  old (`autoResume`), goes full screen under 450px, closes on Escape, and
+  takes the embed snippet's `colors` (`button`, `header` with gradients,
+  `agentMessage`, `background`, `font`, `userMessage`) with the header text
+  derived for contrast. New options `prompt`, `icon`, `colors`, `hideFooter`,
+  `subtitle`, `conversationStarters`, `autoResume`, `labels`; new handle
+  members `screen`, `showScreen`, `openConversation`, `newConversation`. New
+  theme tokens `--ago-launcher-background`, `--ago-launcher-text-color`,
+  `--ago-send-button-background`, `--ago-user-bubble-background`,
+  `--ago-user-bubble-text-color`, `--ago-agent-bubble-text-color`,
+  `--ago-panel-width`.
+- **The ticket form renders in the vanilla widget.** The `form` tool call the
+  agent's `ago_ticketing` tool opens now shows the tenant's contact form in the
+  conversation, on every placement: inline fields from `GET /config`, the
+  embedded (HubSpot) variant, the "not allowed" notice, a green success block,
+  and the composer replaced by a "complete the form" card, then "ticket
+  created" with a New conversation button. New `toolCallForm` option (labels,
+  success text, `userEmail`, callbacks).
+- **`AgoClient.getConfig()`, `AgoClient.createTicket()`, and
+  `AgoClient.getUserIdentity()`.** `ToolCallData` carries the ticketing fields
+  (`displayMode`, `askToTalkToHuman`, `allowedToCreateTicket`, `ticket`,
+  `mode`, `ticketFormId`, `embedHtml`, `embedDescription`), streamed and
+  persisted alike. New exported types `TicketForm`, `TicketField`,
+  `SdkConfig`, `CreateTicketInput`, `CreateTicketResult`.
+
+### Changed
+
+- Nothing for the existing `inline`, `left`, and `right` placements. The
+  `newConversation()` handle method is new on all of them.
+
+## [1.9.0] - 2026-08-28
+
+### Changed
+
+- **`setPageState` result shape.** `applied` is now an array of field names
+  (was a value map). The result also includes `unchanged: string[]` (always
+  present) and `rejected?: Record<string, string>` (present when any field was
+  refused). `success` is `false` when `rejected` is non-empty, `true` otherwise.
+
+### Added
+
+- **Per-field validation.** `setPageState` validates each field's type and enum
+  against the declared schema before calling `set()`. Unknown control names are
+  rejected with the list of available controls. A value equal to the current
+  `get()` is skipped without calling `set()`.
+- **Placeholder dropping.** `null`, `undefined`, and `""` are silently dropped
+  instead of being applied. They appear in no result bucket.
+- **`clearable` option on string controls.** When set, `""` means "clear the
+  field" and is applied instead of dropped. The SDK adds `""` to the enum (if
+  one exists) and appends a clearing hint to the description.
+- **Tagged setter outcomes.** `set()` can return `{ result: "rejected", reason }`
+  to refuse a value, or `{ result: "unchanged" }` to signal the field already
+  holds the requested state. Returning nothing (void) means applied.
+- **Result budget preservation.** When the result exceeds `maxResultBytes`, the
+  SDK preserves `success`, `applied`, `unchanged`, and `rejected` keys before
+  truncating `data`. Without a data source, oversized rejection reasons are
+  shortened in order rather than replaced wholesale.
+- **React `useAgoPageState` re-registration.** The hook re-registers when a
+  control's model-visible signature changes (name, description, schema,
+  `clearable`), so an enum populated by an async fetch updates the advertised
+  schema and runtime validation.
+- **Dev panel local function runner.** `initDevPanel({ enableFunctionRunner: true })`
+  adds a runner that executes registered functions locally via
+  `executeClientFunction`. The function list tracks route changes and the
+  diagnostic sections are collapsible.
+- **Dev panel disposal.** `initDevPanel` now returns an idempotent disposer that
+  removes its panels and unsubscribes all event handlers. Return it from a React
+  effect to keep one connected panel under Strict Mode.
+
+## [1.8.0] - 2026-08-11
+
+### Added
+
+- User feedback: a visitor can say that an answer, or a whole conversation, does
+  not work, and the report reaches the AGO feedback dashboard.
+  - `client.submitFeedback(messageId, rating, { reasons, comment })` now takes
+    what went wrong on top of the thumb. `reasons` is any of `"inaccurate"`,
+    `"incomplete"`, `"information_not_found"`, `"technical_issue"` (exported as
+    `FEEDBACK_REASONS`).
+  - `client.submitConversationFeedback(conversationId, rating, details?)` reports
+    a whole chat. Feedback is stored per message, so it attaches to the
+    conversation's last answer and returns that message id; pass
+    `details.lastMessageId` to skip the lookup.
+  - `feedback: true` on `mountChatWidget`, and `<ChatWidget feedback />`, render
+    a thumbs row under each finished answer with a "what went wrong?" panel on a
+    thumbs-down. Every string is overridable (`labels`), `askWhy: false` keeps
+    thumbs only, and `onSubmit` / `onError` report what went out.
+  - React: `useFeedback()` and `<MessageFeedback messageId={...} />`. Vue:
+    `useFeedback()`. Angular: `AgoService.submitFeedback` /
+    `submitConversationFeedback`.
+
+### Notes
+
+- The details need a backend that accepts them.
+  `POST /api/sdk/v1/messages/{id}/feedback` used to take `rating` only and
+  silently dropped everything else, so reasons and comments never reached the
+  dashboard. It now also takes `reasons` and `comment` and writes the same
+  feedback record the in-app modal creates. The demo account
+  (`https://playground.api.useago.com`) already runs it; a self-hosted tenant on
+  an older build still accepts the rating and ignores the details.
+
 ## [1.7.2] - 2026-08-10
 
 ### Changed

package/README.md

@@ -148,7 +148,12 @@ function InvoiceList() {
 Each control becomes one optional property of a single `setPageState` function,
 so the agent changes only what the user asked for. The current value from each
 `get()` is sent with every message, so the agent knows the state before it
-changes it. Vue and Angular have the same helper.
+changes it. The SDK validates type and enum before calling `set()`, skips values
+that match the current `get()`, and drops placeholders (`null`, `undefined`,
+`""`). The result reports each field in `applied`, `unchanged`, or `rejected`.
+Vue and Angular have the same helper. See
+[Page state shortcut](docs/general/functions-and-context.md#page-state-shortcut)
+for `clearable`, tagged setter outcomes, and the full result envelope.
 
 Add a `data` source and the agent also gets back **what the page now shows**, as
 the result of its own call, so it can answer "did you find dupont?" in the same
@@ -262,6 +267,96 @@ with that partial message instead of rejecting. Vue and Angular have the same
 `stop`, and the vanilla `mountChatWidget` handle gained `stop()`. Details in
 [Stop the answer](docs/general/core.md#stop-the-answer).
 
+## Let the user say "this answer doesn't work"
+
+Pass `feedback` and every finished answer gets a thumbs up / thumbs down. On a
+thumbs-down, a panel asks what went wrong: four reason chips
+(inaccurate, incomplete, information not found, technical issue) and a comment
+box.
+
+```tsx
+<ChatWidget feedback />
+```
+
+```ts
+// vanilla widget
+mountChatWidget("#chat", { config, feedback: true });
+```
+
+The thumb is sent the moment it is clicked, so the signal survives a user who
+ignores the panel. A bare rating is a reaction; a report with a reason or a
+comment also lands in the AGO feedback dashboard, the analytics and the CSV
+export, where someone can act on it.
+
+Driving it yourself, from any framework:
+
+```ts
+await ago.submitFeedback(messageId, "negative", {
+  reasons: ["inaccurate"],
+  comment: "The price it quoted is from last year.",
+});
+
+// the whole chat, not one answer (attached to its last answer)
+await ago.submitConversationFeedback(conversationId, "negative");
+```
+
+React and Vue have a `useFeedback()` hook/composable; React also exports the
+`<MessageFeedback messageId={...} />` row for a custom message list. Details in
+[Feedback](docs/general/widget.md#feedback).
+
+## Let the agent see what broke
+
+"The button does nothing" is easier to answer with the exception in hand. Turn
+on the error watcher and the page's recent JavaScript errors (uncaught
+exceptions with file, line and stack, unhandled rejections, `console.error`
+calls) ride along with every message, deduplicated and capped.
+
+```ts
+const ago = new AgoClient({
+  baseUrl: "https://playground.api.useago.com",
+  agent: "generic-guide",
+  errorWatcher: true, // off by default: error messages can carry PII
+});
+
+// Errors you already catch (error boundaries, framework handlers):
+ago.reportError(error, { component: "OrderTable" });
+```
+
+Same option on `<AgoProvider>`, the Vue plugin, `provideAgo` and
+`mountChatWidget({ config })`. Redact with a `filter`, tune the caps, or use
+`when: { jsErrors: 1 }` in a proactive trigger to nudge right after a crash.
+Details in [JavaScript errors](docs/general/functions-and-context.md#javascript-errors).
+
+## Drop the chat bubble on any page
+
+The hosted embed widget, without the iframe: a launcher in the corner, a teaser
+bubble, and a panel with a home screen, the conversation, and the chat history.
+It reopens the visitor's last thread for two hours and goes full screen on a
+phone.
+
+```ts
+import { mountChatWidget } from "@useago/sdk/widget";
+
+mountChatWidget(document.body, {
+  config: { baseUrl: "https://playground.api.useago.com", agent: "generic-guide" },
+  placement: "bubble",
+  title: "Ask AGO",
+  conversationStarters: [{ label: "What can the SDK do?" }],
+  colors: { button: "#007bff", header: "#03182f" },
+});
+```
+
+Add `loadHomeConfig: true` and the home title, subtitle and starter cards come
+from your AGO dashboard instead of the options above.
+
+When the visitor asks for a human, the agent's ticket form renders inside the
+conversation on every placement, with the fields from your AGO dashboard.
+Conditional questions and choices work across ticketing providers; changing an
+answer clears responses that no longer apply. The API must include the form
+metadata described in the ticket form guide.
+Details in [Floating bubble](docs/general/widget.md#floating-bubble-placement-bubble)
+and [Ticket form](docs/general/widget.md#ticket-form-the-form-tool-call).
+
 ## Show the source docs the agent retrieved
 
 Each assistant message carries the knowledge sources it used in `m.sources`

package/dist/angular.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("./AgoClient-7yXQ6R3O.cjs"),c=require("./autoContinue-CP9pJR-V.cjs");var n=class{constructor(t){this.client=new o.AgoClient(t),this.messages$=this.fromEvent("message:complete"),this.chunks$=this.fromEvent("message:chunk"),this.errors$=this.fromEvent("message:error"),this.messageStart$=this.fromEvent("message:start")}fromEvent(t){const e=this.client;return{subscribe(i){const s=r=>{i.next?.(r)};return e.on(t,s),{unsubscribe:()=>e.off(t,s)}}}}sendMessage(t,e){return this.client.sendMessage(t,e)}stop(){return this.client.stop()}stopMessage(t){return this.client.stopMessage(t)}isGenerating(){return this.client.isGenerating()}getConversations(){return this.client.getConversations().then(t=>t.data)}getConversation(t){return this.client.getConversation(t)}getMessages(t){return this.client.getMessages(t)}submitToolCallForm(t,e){return this.client.submitToolCallForm(t,e)}confirmToolCall(t){return this.client.confirmToolCall(t)}rejectToolCall(t){return this.client.rejectToolCall(t)}submitFeedback(t,e){return this.client.submitFeedback(t,e)}registerFunction(t,e,i){typeof t=="object"?this.client.registerFunction(t):this.client.registerFunction(t,e,i)}unregisterFunction(t){return this.client.unregisterFunction(t)}registerNavigationFunction(t,e){this.client.registerNavigationFunction(t,e)}unregisterNavigationFunction(){this.client.unregisterNavigationFunction()}enableAutoContinueAfterNavigation(t){return c.attachAutoContinueAfterNavigation(this.client,t)}registerPageStateFunction(t,e){this.client.registerPageStateFunction(t,e)}unregisterPageStateFunction(t){this.client.unregisterPageStateFunction(t)}on(t,e){this.client.on(t,e)}off(t,e){this.client.off(t,e)}updateConfig(t){this.client.updateConfig(t)}getClient(){return this.client}destroy(){this.client.destroy()}};function u(t){return{provide:n,useValue:new n(t)}}exports.AgoService=n;exports.provideAgo=u;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./types-mcW8vB1U.cjs"),c=require("./autoContinue-CP9pJR-V.cjs");var n=class{constructor(t){this.client=new r.AgoClient(t),this.messages$=this.fromEvent("message:complete"),this.chunks$=this.fromEvent("message:chunk"),this.errors$=this.fromEvent("message:error"),this.messageStart$=this.fromEvent("message:start")}fromEvent(t){const e=this.client;return{subscribe(i){const s=o=>{i.next?.(o)};return e.on(t,s),{unsubscribe:()=>e.off(t,s)}}}}sendMessage(t,e){return this.client.sendMessage(t,e)}stop(){return this.client.stop()}stopMessage(t){return this.client.stopMessage(t)}isGenerating(){return this.client.isGenerating()}getConversations(){return this.client.getConversations().then(t=>t.data)}getConversation(t){return this.client.getConversation(t)}getMessages(t){return this.client.getMessages(t)}submitToolCallForm(t,e){return this.client.submitToolCallForm(t,e)}confirmToolCall(t){return this.client.confirmToolCall(t)}rejectToolCall(t){return this.client.rejectToolCall(t)}submitFeedback(t,e,i){return this.client.submitFeedback(t,e,i)}submitConversationFeedback(t,e,i){return this.client.submitConversationFeedback(t,e,i)}registerFunction(t,e,i){typeof t=="object"?this.client.registerFunction(t):this.client.registerFunction(t,e,i)}unregisterFunction(t){return this.client.unregisterFunction(t)}registerNavigationFunction(t,e){this.client.registerNavigationFunction(t,e)}unregisterNavigationFunction(){this.client.unregisterNavigationFunction()}enableAutoContinueAfterNavigation(t){return c.attachAutoContinueAfterNavigation(this.client,t)}registerPageStateFunction(t,e){this.client.registerPageStateFunction(t,e)}unregisterPageStateFunction(t){this.client.unregisterPageStateFunction(t)}on(t,e){this.client.on(t,e)}off(t,e){this.client.off(t,e)}updateConfig(t){this.client.updateConfig(t)}getClient(){return this.client}destroy(){this.client.destroy()}};function u(t){return{provide:n,useValue:new n(t)}}exports.AgoService=n;exports.FEEDBACK_REASONS=r.FEEDBACK_REASONS;exports.provideAgo=u;