@useago/sdk 1.9.0 → 1.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/CHANGELOG.md +173 -2
  2. package/README.md +126 -0
  3. package/dist/angular.cjs +1 -1
  4. package/dist/angular.d.cts +408 -26
  5. package/dist/angular.d.ts +408 -26
  6. package/dist/angular.js +4 -1
  7. package/dist/{createConversationSession-BaaXBQ5b.js → createConversationSession-BfJg0WyA.js} +1 -1
  8. package/dist/{createConversationSession-CU0b-t1W.cjs → createConversationSession-CiOXKWl0.cjs} +1 -1
  9. package/dist/{createFormCollector-Cf7kGhCB.js → createFormCollector-DN1xjAv5.js} +1 -1
  10. package/dist/{createFormCollector-DfN1xZBy.cjs → createFormCollector-DnQl77Ko.cjs} +1 -1
  11. package/dist/createMockClient-BPt1gSve.cjs +1 -0
  12. package/dist/{createMockClient-5YF-ZbVu.js → createMockClient-YoYr3pQr.js} +16 -3
  13. package/dist/devtools.cjs +4 -4
  14. package/dist/devtools.d.cts +406 -26
  15. package/dist/devtools.d.ts +406 -26
  16. package/dist/devtools.js +87 -84
  17. package/dist/helpers.d.cts +42 -12
  18. package/dist/helpers.d.ts +42 -12
  19. package/dist/index.cjs +1 -1
  20. package/dist/index.d.cts +486 -35
  21. package/dist/index.d.ts +486 -35
  22. package/dist/index.js +117 -112
  23. package/dist/react.cjs +4 -4
  24. package/dist/react.d.cts +458 -26
  25. package/dist/react.d.ts +458 -26
  26. package/dist/react.js +816 -727
  27. package/dist/speechToText-BV7qxqPF.js +704 -0
  28. package/dist/speechToText-ZciRyyJE.cjs +1 -0
  29. package/dist/testing.cjs +1 -1
  30. package/dist/testing.d.cts +406 -26
  31. package/dist/testing.d.ts +406 -26
  32. package/dist/testing.js +1 -1
  33. package/dist/types-Q7t1peH-.js +2584 -0
  34. package/dist/types-a7teDBnC.cjs +10 -0
  35. package/dist/vue.cjs +1 -1
  36. package/dist/vue.d.cts +608 -26
  37. package/dist/vue.d.ts +608 -26
  38. package/dist/vue.js +103 -101
  39. package/dist/widget.cjs +6 -4
  40. package/dist/widget.d.cts +710 -28
  41. package/dist/widget.d.ts +710 -28
  42. package/dist/widget.js +3911 -976
  43. package/llms-full.txt +254 -7
  44. package/package.json +1 -1
  45. package/dist/createMockClient-BZbOe-23.cjs +0 -1
  46. package/dist/sheetController-CBUVOroo.js +0 -205
  47. package/dist/sheetController-DY-sC13T.cjs +0 -1
  48. package/dist/types-CPga11Of.js +0 -2068
  49. package/dist/types-D3YQl1jx.cjs +0 -9
package/llms-full.txt CHANGED
@@ -386,7 +386,10 @@ widget.destroy(); // removes listeners, uninstalls forms, clears the DOM
386
386
  While the agent answers, the send button becomes a Stop button that interrupts
387
387
  the turn; pass `allowStop: false` to keep a disabled spinner instead.
388
388
  Set `placement: "left"` or `"right"` for a fixed full-height side panel with a
389
- launcher button. Set `persistConversation: true` to resume the visitor's last
389
+ launcher button, or `placement: "bubble"` for the hosted widget's floating
390
+ bubble (home / chat / history screens); with `loadHomeConfig: true` the bubble's
391
+ home title, subtitle and starter cards come from the AGO dashboard.
392
+ Set `persistConversation: true` to resume the visitor's last
390
393
  thread across reloads. Set `feedback: true` to put thumbs under each answer,
391
394
  with a "what went wrong?" panel on a thumbs-down. Theme it with the `theme` option or `--ago-*` CSS variables
392
395
  on `.ago-chat-widget`. Message text renders as GitHub-flavored markdown and is
@@ -1319,7 +1322,8 @@ reference, and the framework guides show the idiomatic wrappers.
1319
1322
 
1320
1323
  - [Client-side functions](#client-side-functions): the agent runs code in the browser
1321
1324
  - [Pre-built helpers](#pre-built-helpers): a catalogue of ready-made functions
1322
- - [Client context](#client-context): tell the agent what the user is doing
1325
+ - [Client context](#client-context): tell the agent what the user is doing,
1326
+ including the [JavaScript errors](#javascript-errors) the page hit
1323
1327
 
1324
1328
  ---
1325
1329
 
@@ -1763,6 +1767,74 @@ user declined, then lets the turn resume. This is a no-op in placeholder mode
1763
1767
  In React, `useAgoActivity` surfaces awaiting items with ready-made `approve` /
1764
1768
  `reject` controls (see the [React guide](../frameworks/react.md)).
1765
1769
 
1770
+ ### WebMCP bridge (share your functions with browser agents)
1771
+
1772
+ [WebMCP](https://github.com/webmachinelearning/webmcp) is a browser API that lets
1773
+ a page hand tools to whatever agent the user brings, such as an agentic browser
1774
+ or an extension. Set `webmcp` and every function you register becomes a WebMCP
1775
+ tool as well.
1776
+
1777
+ ```ts
1778
+ const client = new AgoClient({
1779
+ baseUrl: "https://playground.api.useago.com",
1780
+ agent: "your-agent",
1781
+ webmcp: true,
1782
+ });
1783
+
1784
+ client.registerFunction({
1785
+ name: "listFlights",
1786
+ description: "The flights currently on screen, after filtering.",
1787
+ parameters: { type: "object", properties: {} },
1788
+ handler: () => visibleFlights(),
1789
+ // Optional, WebMCP only: MCP behavior hints.
1790
+ webmcp: { annotations: { readOnlyHint: true } },
1791
+ });
1792
+ ```
1793
+
1794
+ In React it is a prop:
1795
+
1796
+ ```tsx
1797
+ <AgoProvider baseUrl="https://playground.api.useago.com" agent="your-agent" webmcp>
1798
+ <App />
1799
+ </AgoProvider>
1800
+ ```
1801
+
1802
+ A function a page registers on mount disappears from the browser's tool list
1803
+ when that page unmounts. That is a problem for navigation: the handler returns
1804
+ before the destination page has mounted, so the caller would read the tools of
1805
+ the page it just left. Mark the function and the SDK holds the call open until
1806
+ the destination has registered:
1807
+
1808
+ ```ts
1809
+ client.registerFunction({
1810
+ name: "openOrder",
1811
+ description: "Open one order's detail page.",
1812
+ parameters: { type: "object", properties: { id: { type: "string" } } },
1813
+ handler: (args) => navigate(`/orders/${args.id}`),
1814
+ webmcp: { navigates: true },
1815
+ });
1816
+ ```
1817
+
1818
+ The built-in `navigateToPage` already carries it, so
1819
+ [`registerNavigationFunction`](#navigation-shortcut) and `useAgoNavigation` need
1820
+ no change. The call resolves 150 ms after the last registration, 600 ms if the
1821
+ destination registers nothing, and gives up after 4 seconds.
1822
+
1823
+ Check what is exposed from the console:
1824
+
1825
+ ```js
1826
+ (await document.modelContext.getTools()).map((t) => t.name);
1827
+ ```
1828
+
1829
+ Off by default, and a no-op in browsers without WebMCP. Calls arrive as
1830
+ `function:invoke` and `function:result` like any other, so your logging and the
1831
+ dev panel already cover them.
1832
+
1833
+ **There is no approval gate on a WebMCP call**, and cancelling one does not stop
1834
+ your handler. `requiresApproval` and `approvalPolicy` hold a call in the agent
1835
+ loop, which a WebMCP call never enters. Set `webmcp: false` on a definition to
1836
+ keep that function private to your own agent.
1837
+
1766
1838
  ---
1767
1839
 
1768
1840
  ## Pre-built helpers
@@ -1918,11 +1990,94 @@ event can't bloat the context. Read or clear the log with
1918
1990
  `client.getRecentActivity()` / `client.clearActivity()`, observe it via
1919
1991
  `client.on("activity:recorded", …)`, or use the React `useAgoActivityLog()` hook.
1920
1992
 
1993
+ ### JavaScript errors
1994
+
1995
+ "The button does nothing" is much easier to answer when the agent can see the
1996
+ exception behind it. Turn the error watcher on and the page's recent JavaScript
1997
+ errors ride along with every message:
1998
+
1999
+ ```ts
2000
+ const client = new AgoClient({
2001
+ baseUrl: "https://playground.api.useago.com",
2002
+ agent: "generic-guide",
2003
+ errorWatcher: true,
2004
+ });
2005
+ ```
2006
+
2007
+ (`<AgoProvider errorWatcher>`, the Vue plugin and `provideAgo` take the same
2008
+ option, and so does `mountChatWidget({ config: { errorWatcher: true } })`.)
2009
+
2010
+ With it on, the SDK captures:
2011
+
2012
+ - uncaught exceptions (the `window` `error` event), with file, line and stack;
2013
+ - unhandled promise rejections;
2014
+ - every `console.error` call (see the note below);
2015
+ - errors your app caught itself and hands over with `client.reportError()`.
2016
+
2017
+ They go out as the `errors:recent` context entry: at most 10 distinct errors,
2018
+ deduplicated with a `count`, each with how long ago it last fired, pruned after
2019
+ 10 minutes. Messages are cut at 500 characters and stacks at 2000, so one crash
2020
+ cannot flood the context. The entry is absent when nothing happened.
2021
+
2022
+ Report the errors you already catch, so the agent sees them too:
2023
+
2024
+ ```tsx
2025
+ // React error boundary
2026
+ componentDidCatch(error, info) {
2027
+ this.props.client.reportError(error, { componentStack: info.componentStack });
2028
+ }
2029
+
2030
+ // Vue
2031
+ app.config.errorHandler = (err, _instance, info) => client.reportError(err, { info });
2032
+
2033
+ // Angular
2034
+ @Injectable() class AgoErrorHandler implements ErrorHandler {
2035
+ constructor(private ago: AgoService) {}
2036
+ handleError(error: unknown) { this.ago.getClient().reportError(error); }
2037
+ }
2038
+ ```
2039
+
2040
+ Tune the caps or redact what leaves the page with options instead of `true`:
2041
+
2042
+ ```ts
2043
+ new AgoClient({
2044
+ baseUrl: "https://playground.api.useago.com",
2045
+ errorWatcher: {
2046
+ maxErrors: 5, // distinct errors kept (default 10)
2047
+ maxAgeMs: 120_000, // forget errors older than 2 min (default 10 min)
2048
+ maxStackChars: 1000, // default 2000
2049
+ // Return null to drop an error, or an edited copy to redact it.
2050
+ filter: (e) => (e.message.includes("token") ? null : e),
2051
+ },
2052
+ });
2053
+ ```
2054
+
2055
+ Things to know:
2056
+
2057
+ - **It is off by default.** Error messages can contain emails, ids or internal
2058
+ URLs. Enabling it is your call; use `filter` if some of them must stay home.
2059
+ - **`console.error` is wrapped.** The SDK never touches globals otherwise, but
2060
+ most caught errors (React render errors included) only surface there. The
2061
+ wrapper calls the original every time and is restored on `destroy()`.
2062
+ - **Cross-origin scripts** without a `crossorigin` attribute only yield
2063
+ `Script error.` with no details. That is the browser, not the SDK.
2064
+ - Errors also count as friction for the proactive mode: a trigger can use
2065
+ `when: { jsErrors: 1 }` to nudge right after a crash.
2066
+
2067
+ Observe or inspect it with `client.on("error:captured", …)`,
2068
+ `client.getRecentErrors()`, `client.clearErrors()`, or toggle it at runtime
2069
+ with `client.updateConfig({ errorWatcher: false })`.
2070
+
2071
+ To see it work, `examples/simple-html/error-watcher.html` is an order page
2072
+ with three planted bugs (a `TypeError`, an unhandled rejection, a swallowed
2073
+ error logged with `console.error`) and the bubble widget wired to the same
2074
+ client. Build the SDK, serve the repo, click a button, ask the agent what broke.
2075
+
1921
2076
  ### Per framework
1922
2077
 
1923
2078
  | Framework | Idiomatic API |
1924
2079
  | --- | --- |
1925
- | Core | `setContext` / `addDynamicContext` / `enableAutoPageContext` |
2080
+ | Core | `setContext` / `addDynamicContext` / `enableAutoPageContext` / `errorWatcher` |
1926
2081
  | React | `useAgoContext(entryOrFn, key?)` + `pageContext="auto"` |
1927
2082
  | Vue | core API inside `onMounted` / `onUnmounted` |
1928
2083
  | Angular | `agoService.getClient().setContext(…)` |
@@ -1984,6 +2139,7 @@ const final = await client.waitFor("message:complete", { timeout: 10_000 });
1984
2139
  | `function:awaiting-approval` | `{ invocationId, functionName, arguments, conversationId }`: a client function call is held pending user approval (pause mode + an `approvalPolicy`/`requiresApproval` match). The turn stays at `WAITING_CLIENT`; call `approveFunction(invocationId)` to run it and resume, or `rejectFunction(invocationId)` to decline. See [Approval gate](functions-and-context.md#approval-gate-ask-before-running) |
1985
2140
  | `function:result` | `{ invocationId, result, error? }` |
1986
2141
  | `activity:recorded` | `ActivityEntry`: a user- or agent-action was recorded into the activity ledger (via `recordActivity`, or auto-recorded when the agent calls a client function). See [Activity ledger](functions-and-context.md#activity-ledger) |
2142
+ | `error:captured` | `CapturedError`: the error watcher captured a JavaScript error (uncaught exception, unhandled rejection, `console.error`, or `reportError`). Fires on repeats too, with the updated `count`. Needs `errorWatcher` in the config. See [JavaScript errors](functions-and-context.md#javascript-errors) |
1987
2143
  | `form:submitted` | `{ name, values, result }`: a form collector submitted successfully; `result` is the submit response (the third-party API's answer) |
1988
2144
  | `form:error` | `{ name, values, error }`: a form collector submit failed at the network/server level (HTTP non-2xx or a thrown handler/fetch). Validation pre-checks (missing fields, no submit target) do not fire this |
1989
2145
  | `connection:status` | `{ connected }` |
@@ -2103,6 +2259,14 @@ client.on("toolCall:received", async (toolCall) => {
2103
2259
  `ToolCallType` is one of: `form`, `confirmation_input`, `status_message`,
2104
2260
  `progress_indicator`, `client_function`, `reasoning`, `mcp_ui_resource`.
2105
2261
 
2262
+ A `form` tool call from the agent's `ago_ticketing` tool is the ticket form:
2263
+ `toolName` is `"ago_ticketing"`, `formSchema` is empty, and the fields come from
2264
+ `getConfig().permissions[0].ticketForm` instead. The call carries the agent's
2265
+ pre-filled `ticket`, `allowedToCreateTicket`, and for embed-mode forms
2266
+ `embedHtml`. The vanilla widget renders and submits it for you (see
2267
+ [Ticket form](widget.md#ticket-form-the-form-tool-call)); a custom UI creates
2268
+ the ticket with `createTicket()` and then calls `submitToolCallForm(id, { success: true, ticket_id, ticket_url })`.
2269
+
2106
2270
  ---
2107
2271
 
2108
2272
  ## Framework equivalents
@@ -2139,12 +2303,15 @@ interface AgoConfig {
2139
2303
  agent?: string; // default agent (id or slug) for new conversations
2140
2304
  defaultAgentId?: string; // same as `agent`; `agent` is preferred
2141
2305
  permission?: string; // X-Widget-Permission header
2306
+ language?: string | null; // Host interface locale, sent as Accept-Language
2142
2307
  userEmail?: string; // X-User-Email header, identify the end user
2143
2308
  userJwt?: string; // Authorization: Bearer <jwt>, authenticated users
2309
+ metadata?: Record<string, unknown> | null; // Message body, for user/ticket enrichment
2144
2310
  debug?: boolean; // enable verbose console logging
2145
2311
  warnOnEmptyReply?: boolean; // default true; see "Empty replies" below
2146
2312
  clientFunctionsMode?: "placeholder" | "pause"; // default "pause"
2147
2313
  maxFunctionResultBytes?: number; // default 50000; cap on client function results
2314
+ errorWatcher?: boolean | ErrorWatcherOptions; // default off; send recent JS errors as context
2148
2315
  }
2149
2316
  ```
2150
2317
 
@@ -2154,12 +2321,15 @@ interface AgoConfig {
2154
2321
  | `widgetId` | — | `X-User-Anon-Id` | Per-visitor anonymous id. If omitted, a UUID is generated and cached in `localStorage` (`ago_widget_id`) so a returning visitor keeps the same id. |
2155
2322
  | `agent` / `defaultAgentId` | — | `agent_id` in the body | Per-message `agentId` overrides it. `agent` wins if both are set. |
2156
2323
  | `permission` | — | `X-Widget-Permission` | Mirrors the widget's `window.AGO.permission`. |
2324
+ | `language` | No | `Accept-Language` | Pass your interface locale, such as `fr` or `pt-BR`. `null` clears the override. |
2157
2325
  | `userEmail` | — | `X-User-Email` | Identifies the user to AGO. |
2158
2326
  | `userJwt` | — | `Authorization: Bearer …` | For authenticated sessions. |
2327
+ | `metadata` | — | `metadata` in the body | JSON-serializable user/ticket context. Per-message overrides replace defaults; `null` omits the field. |
2159
2328
  | `debug` | — | — | Turns on the SDK's logger. |
2160
2329
  | `warnOnEmptyReply` | — | — | Default `true`: warn on the console (once per conversation) when a reply completes empty, usually an unknown `agent` slug. The [`message:empty` event](events-and-streaming.md#events) fires regardless. |
2161
2330
  | `clientFunctionsMode` | — | `client_functions_mode` in the body | Default `"pause"`: the agent stops on client function call(s) and resumes the SAME turn once the results are submitted (the SDK submits and resumes automatically; see the [`message:waiting-client` event](events-and-streaming.md#events)). Needs a backend with pause/resume support; older backends ignore the flag and fall back to placeholder behavior. Legacy `"placeholder"`: the turn continues on a placeholder and results are only visible on later turns. Per-message override via `sendMessage(..., { clientFunctionsMode })`. |
2162
2331
  | `maxFunctionResultBytes` | — | — | Default `50000`. Client function results larger than this (serialized) are replaced with a truncated preview before reaching the LLM. Override per function with `maxResultBytes`; see [result size limit](functions-and-context.md#result-size-limit). |
2332
+ | `errorWatcher` | — | `errors:recent` in `client_context` | Off by default. `true` (or options) captures the page's JavaScript errors (uncaught exceptions, unhandled rejections, `console.error`, `reportError`) and sends the recent ones with every message. See [JavaScript errors](functions-and-context.md#javascript-errors). |
2163
2333
 
2164
2334
  ---
2165
2335
 
@@ -2221,7 +2391,7 @@ provideAgo({ baseUrl: "https://acme.useago.com", agent: "support" });
2221
2391
  order:
2222
2392
 
2223
2393
  1. **`window.AGO`** (the widget config object): `basepath`, `widgetId`,
2224
- `agent`/`defaultAgent`, `permission`, `email`, `jwt`.
2394
+ `agent`/`defaultAgent`, `permission`, `email`, `jwt`, `metadata`.
2225
2395
  2. **`<meta>` tags**: `ago-base-url`, `ago-widget-id`, `ago-agent`
2226
2396
  (or `ago-agent-id`), `ago-permission`, `ago-user-email`.
2227
2397
  3. **`data-ago-*` attributes** on `<body>` or a `<script>` tag:
@@ -2254,14 +2424,90 @@ client.updateConfig({ userJwt: token, userEmail: "jane@acme.com" });
2254
2424
  ```
2255
2425
 
2256
2426
  Changing `permission` to a falsy value removes the header. In React, the
2257
- `useAgo` hook re-applies `agent`, `permission`, `userEmail`, `userJwt`,
2258
- `debug` and `warnOnEmptyReply` automatically when those props change (changing
2259
- `baseUrl`/`widgetId` recreates the client).
2427
+ `useAgo` hook re-applies `agent`, `permission`, `language`, `userEmail`, `userJwt`,
2428
+ `metadata`, `debug` and `warnOnEmptyReply` automatically when those props
2429
+ change (changing `baseUrl`/`widgetId` recreates the client).
2260
2430
 
2261
2431
  `updateConfig` validates the merged result: omitting a key (or passing it as
2262
2432
  `undefined`) keeps the current value; an explicit empty or non-string `baseUrl`
2263
2433
  throws `config_missing_base_url` and leaves the client unchanged.
2264
2434
 
2435
+ ### Language
2436
+
2437
+ ```ts
2438
+ const client = new AgoClient({
2439
+ baseUrl: "https://playground.api.useago.com",
2440
+ agent: "generic-guide",
2441
+ language: "fr",
2442
+ });
2443
+ const answer = await client.sendMessage("What can you help me with?");
2444
+
2445
+ // Run this when your application's language picker changes.
2446
+ client.updateConfig({ language: "de" });
2447
+ await client.sendMessage("And now?", { conversationId: answer.conversationId });
2448
+ ```
2449
+
2450
+ Pass your application's current locale to `language`. The SDK sends it in the
2451
+ `Accept-Language` header on its requests. AGO uses the resolved language to select
2452
+ existing knowledge translations and source titles, falling back to the original
2453
+ content when a translation is unavailable. Region tags are preserved in the header
2454
+ (`pt-BR`); underscores are accepted (`fr_FR` becomes `fr-FR`). The backend may resolve
2455
+ a regional tag to its base language. If translations are stored under a base
2456
+ language such as `pt`, pass that code when the backend does not fall back from
2457
+ `pt-BR`. Source URLs remain the document's configured URLs.
2458
+ If a Django language cookie is sent with the
2459
+ request, it takes precedence over this header.
2460
+
2461
+ In React, bind the same locale your interface uses:
2462
+
2463
+ ```tsx
2464
+ <AgoProvider baseUrl="https://playground.api.useago.com" language={i18n.language}>
2465
+ <App />
2466
+ </AgoProvider>
2467
+ ```
2468
+
2469
+ Changing the prop updates subsequent requests without recreating the client or
2470
+ losing the conversation. Omit the React prop or call
2471
+ `client.updateConfig({ language: null })` to clear the override. With no override,
2472
+ the browser supplies its own language header. Each client has its own setting;
2473
+ the SDK does not read or change your
2474
+ page's language, global variables, or saved language preferences.
2475
+
2476
+ To refresh knowledge source titles already on screen, reload the conversation
2477
+ after changing the language. Existing answer text stays unchanged:
2478
+
2479
+ ```ts
2480
+ client.updateConfig({ language: "fr" });
2481
+ const conversation = await client.getConversation(answer.conversationId);
2482
+ const sources = conversation.messages?.flatMap((message) => message.sources ?? []);
2483
+ ```
2484
+
2485
+ `createAgo({ language: "fr" })` also accepts an explicit locale when your API
2486
+ configuration is detected from the page.
2487
+
2488
+ This header does not force the agent's reply language or translate your UI text.
2489
+ Continue passing translated labels, placeholders and welcome text from your
2490
+ application's translations.
2491
+
2492
+ ### User and ticket metadata
2493
+
2494
+ Pass JSON-serializable data in `config.metadata` to include it in every new
2495
+ message request (JSON and multipart uploads). `sendMessage(text, { metadata })`
2496
+ replaces those defaults for that message; it does not merge objects. `null`
2497
+ omits metadata. `updateConfig({ metadata: null })` stops sending defaults; it
2498
+ does not erase data already stored by the server.
2499
+
2500
+ ```ts
2501
+ client.updateConfig({ metadata: { brevo: { clientid: 11970100, planCategory: "Free" } } });
2502
+ await client.sendMessage("I need help");
2503
+ ```
2504
+
2505
+ The AGO API stores this data as widget metadata on the user. Configure metadata
2506
+ field mappings in AGO to include selected fields in tickets. This does not
2507
+ populate a separately hosted Zendesk form. Use `setContext` as well when the
2508
+ agent needs these values in its prompt. Metadata supplied by the browser is
2509
+ untrusted context, not an authentication credential or permission grant.
2510
+
2265
2511
  ---
2266
2512
 
2267
2513
  ## Errors
@@ -2301,6 +2547,7 @@ may be reworded in any release.
2301
2547
  | Code | Thrown by | Meaning | Fix |
2302
2548
  | --- | --- | --- | --- |
2303
2549
  | `config_missing_base_url` | `AgoError` | `baseUrl` missing, empty, or not a string (also from `createAgo()` and `mountChatWidget`) | Pass `baseUrl`, e.g. `https://YOUR-DOMAIN.api.useago.com` (the public demo account `https://playground.api.useago.com` works without a tenant) |
2550
+ | `config_invalid_language` | `AgoError` | `language` is not a valid language tag | Use a tag such as `fr` or `pt-BR`, or `null` to clear the override. Invalid updates leave the client unchanged. |
2304
2551
  | `config_suspect_base_url` | console warning only | `baseUrl` has no protocol and is not a `/path` | Add `https://`, or use a `/path` for a same-origin proxy |
2305
2552
  | `network_error` | `AgoNetworkError` | fetch failed (offline, DNS, unreachable host) | Check `baseUrl` is reachable and includes the protocol |
2306
2553
  | `http_error` | `AgoApiError` | non-2xx without a structured error body | 401/403: check `userJwt`. 404: check `baseUrl` points at the API root |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@useago/sdk",
3
- "version": "1.9.0",
3
+ "version": "1.13.0",
4
4
  "description": "Create In-APP AI agents that answers question and performs actions. Works with React, Vue, Angular and vanilla JS/TS.",
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -1 +0,0 @@
1
- function y(u={}){const{overrides:g={}}=u,a={id:"mock-msg-1",conversationId:"mock-conv-1",content:"Mock response",role:"assistant",status:"DONE",createdAt:new Date},l={id:"mock-conv-1",title:"Mock Conversation",lastMessageDate:new Date},n=new Map,c=[],m={sendMessage:async()=>a,continueMessage:async()=>a,stop:async()=>null,stopMessage:async()=>({status:"not_running"}),isGenerating:()=>!1,resumePendingClientFunctions:async()=>null,registerResumeGate:()=>()=>{},getConversations:async()=>[l],getConversation:async()=>l,getMessages:async()=>[a],submitToolCallForm:async()=>({status:"completed"}),confirmToolCall:async()=>{},rejectToolCall:async()=>{},submitFeedback:async()=>{},submitConversationFeedback:async()=>a.id,registerFunction:()=>{},unregisterFunction:()=>!0,getRegisteredFunctions:()=>[],executeClientFunction:async()=>{},getContextSnapshot:()=>null,notifyContextChanged:()=>{},setContext:()=>{},removeContext:()=>!0,addDynamicContext:()=>{},removeDynamicContext:()=>!0,registerNavigationFunction:()=>{},unregisterNavigationFunction:()=>{},getConfiguredAgent:()=>{},getHttp:()=>({get:async()=>({}),post:async()=>({})}),emitProactiveEvent:(e,t)=>{const o=n.get(e);o&&[...o].forEach(s=>s(t))},on:(e,t)=>{n.has(e)||n.set(e,new Set),n.get(e).add(t)},off:(e,t)=>{n.get(e)?.delete(t)},once:(e,t)=>{const o=(...s)=>{n.get(e)?.delete(o),t(...s)};n.has(e)||n.set(e,new Set),n.get(e).add(o)},waitFor:(e,t)=>new Promise((o,s)=>{let r;const d=f=>{r&&clearTimeout(r),n.get(e)?.delete(d),o(f)};n.has(e)||n.set(e,new Set),n.get(e).add(d),t?.timeout&&(r=setTimeout(()=>{n.get(e)?.delete(d),s(new Error(`waitFor("${e}") timed out after ${t.timeout}ms`))},t.timeout))}),updateConfig:()=>{},destroy:()=>{n.clear()},...g},i={};for(const[e,t]of Object.entries(m))i[e]=(...o)=>(c.push({method:e,args:o}),t(...o));return i.proactive=null,i.__calls=c,i.__callsFor=e=>c.filter(t=>t.method===e),i.__emitEvent=(e,t)=>{const o=n.get(e);o&&[...o].forEach(s=>s(t))},i}Object.defineProperty(exports,"createMockClient",{enumerable:!0,get:function(){return y}});
@@ -1,205 +0,0 @@
1
- var u = /* @__PURE__ */ new WeakMap(), A = [
2
- "position",
3
- "top",
4
- "left",
5
- "right",
6
- "width"
7
- ];
8
- function x(e, t) {
9
- return t.map((a) => ({
10
- style: e,
11
- prop: a,
12
- value: e.getPropertyValue(a),
13
- priority: e.getPropertyPriority(a)
14
- }));
15
- }
16
- function T(e) {
17
- for (const { style: t, prop: a, value: r, priority: n } of e) r ? t.setProperty(a, r, n) : t.removeProperty(a);
18
- }
19
- function N(e, t = document) {
20
- const a = u.get(t);
21
- if (a) {
22
- a.owners.add(e);
23
- return;
24
- }
25
- const r = t.body, n = t.documentElement, s = t.defaultView?.scrollY ?? 0;
26
- u.set(t, {
27
- owners: /* @__PURE__ */ new Set([e]),
28
- saved: [...x(r.style, A), ...x(n.style, ["overflow"])],
29
- scrollY: s
30
- }), r.style.position = "fixed", r.style.top = `-${s}px`, r.style.left = "0", r.style.right = "0", r.style.width = "100%", n.style.overflow = "hidden";
31
- }
32
- function P(e, t = document) {
33
- const a = u.get(t);
34
- !a || !a.owners.delete(e) || a.owners.size > 0 || (u.delete(t), T(a.saved), t.defaultView?.scrollTo(0, a.scrollY));
35
- }
36
- var w = '"IBM Plex Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif', I = `var(--ago-font, ${w})`, S = {
37
- font: "--ago-font",
38
- radius: "--ago-radius",
39
- messageRadius: "--ago-message-radius",
40
- brand: "--ago-brand-color",
41
- brandText: "--ago-brand-text-color",
42
- headerBg: "--ago-header-background",
43
- headerText: "--ago-header-text-color",
44
- panelBg: "--ago-panel-background",
45
- messagesBg: "--ago-messages-background",
46
- text: "--ago-text-color",
47
- mutedText: "--ago-muted-text-color",
48
- border: "--ago-border-color",
49
- accent: "--ago-accent-color",
50
- agentBubbleBg: "--ago-agent-bubble-background"
51
- }, U = "var(--ago-brand-color, #03182f)", G = "var(--ago-brand-text-color, #fff)", H = "var(--ago-header-background, var(--ago-brand-color, #03182f))", K = "var(--ago-header-text-color, #e8f0fe)", $ = "var(--ago-panel-background, #fff)", F = "var(--ago-messages-background, #fbfbfb)", V = "var(--ago-text-color, #30373e)", X = "var(--ago-muted-text-color, #6b6d6f)", Y = "var(--ago-border-color, #dee3e8)", z = "var(--ago-accent-color, #1b5fc4)", j = "var(--ago-agent-bubble-background, #f1f3f5)", k = "var(--ago-radius, 16px)", q = "var(--ago-message-radius, 16px)", Q = "var(--ago-message-radius, 20px)";
52
- function W(e, t) {
53
- if (t)
54
- for (const a of Object.keys(S)) {
55
- const r = t[a];
56
- r != null && e.style.setProperty(S[a], r);
57
- }
58
- }
59
- function C(e, t) {
60
- Object.assign(e.style, t);
61
- }
62
- function Z(e = {}) {
63
- const t = document.createElement("div");
64
- return C(t, e), t;
65
- }
66
- var O = "ago-chat-widget-keyframes";
67
- function J() {
68
- if (typeof document > "u" || document.getElementById(O)) return;
69
- const e = document.createElement("style");
70
- e.id = O, e.textContent = "@keyframes ago-pulse { 0%, 80%, 100% { opacity: 0.3; transform: scale(0.8); } 40% { opacity: 1; transform: scale(1); } }@keyframes ago-spin { to { transform: rotate(360deg); } }", document.head.appendChild(e);
71
- }
72
- var D = "2147483000";
73
- function M(e, t = "0px") {
74
- return e === void 0 ? t : typeof e == "number" ? `${e}px` : e;
75
- }
76
- function L(e) {
77
- return `(max-width: ${e}px), (max-height: 500px) and (orientation: landscape)`;
78
- }
79
- function ee(e = {}) {
80
- const t = e.breakpoint ?? 768, a = e.peekHeight ?? 152, r = M(e.bottomOffset), n = e.initialState ?? "peek", s = /* @__PURE__ */ new Set();
81
- let i = n, d = !1;
82
- const c = typeof window < "u" && typeof window.matchMedia == "function" ? window.matchMedia(L(t)) : void 0;
83
- let g = p();
84
- const R = m(!1, n);
85
- function _(o, l) {
86
- if (!o) return {
87
- style: {},
88
- attrs: {
89
- role: null,
90
- "aria-modal": null,
91
- "aria-label": null
92
- }
93
- };
94
- const E = {
95
- position: "fixed",
96
- left: "0",
97
- right: "0",
98
- bottom: r,
99
- zIndex: D,
100
- display: "flex",
101
- flexDirection: "column",
102
- borderRadius: l === "full" ? "0" : `${k} ${k} 0 0`,
103
- paddingBottom: "env(safe-area-inset-bottom)"
104
- };
105
- return l === "full" ? {
106
- style: {
107
- ...E,
108
- top: "0",
109
- height: "auto",
110
- paddingTop: "env(safe-area-inset-top)"
111
- },
112
- attrs: {
113
- role: "dialog",
114
- "aria-modal": "true",
115
- tabindex: "-1"
116
- }
117
- } : {
118
- style: {
119
- ...E,
120
- top: "auto",
121
- minHeight: `calc(${a}px + env(safe-area-inset-bottom))`,
122
- height: "auto"
123
- },
124
- attrs: {
125
- role: null,
126
- "aria-modal": null,
127
- tabindex: "-1"
128
- }
129
- };
130
- }
131
- function m(o, l) {
132
- return {
133
- compact: o,
134
- state: l,
135
- isModal: o && l === "full",
136
- surface: _(o, l)
137
- };
138
- }
139
- function p() {
140
- return m(!!c?.matches, i);
141
- }
142
- function v() {
143
- g = p();
144
- for (const o of s) o();
145
- }
146
- function b(o, l) {
147
- d || i === o || (i = o, v(), e.onStateChange?.(o, l));
148
- }
149
- function y() {
150
- if (!d) {
151
- if (!c?.matches && i !== n) {
152
- i = n, v(), e.onStateChange?.(n, "breakpoint");
153
- return;
154
- }
155
- v();
156
- }
157
- }
158
- let f = !1;
159
- function B() {
160
- f || !c || (c.addEventListener("change", y), f = !0, g = p());
161
- }
162
- function h() {
163
- !f || !c || (c.removeEventListener("change", y), f = !1);
164
- }
165
- return {
166
- subscribe(o) {
167
- return s.add(o), s.size === 1 && B(), () => {
168
- s.delete(o), s.size === 0 && h();
169
- };
170
- },
171
- getSnapshot: () => g,
172
- getServerSnapshot: () => R,
173
- expand: (o = "api") => b("full", o),
174
- collapse: (o = "api") => b("peek", o),
175
- toggle: (o = "api") => b(i === "full" ? "peek" : "full", o),
176
- destroy() {
177
- d || (d = !0, h(), s.clear());
178
- }
179
- };
180
- }
181
- export {
182
- P as C,
183
- N as S,
184
- V as _,
185
- Y as a,
186
- Z as b,
187
- I as c,
188
- F as d,
189
- q as f,
190
- k as g,
191
- $ as h,
192
- j as i,
193
- H as l,
194
- X as m,
195
- ee as n,
196
- U as o,
197
- Q as p,
198
- z as r,
199
- G as s,
200
- L as t,
201
- K as u,
202
- W as v,
203
- J as x,
204
- C as y
205
- };
@@ -1 +0,0 @@
1
- var d=new WeakMap,D=["position","top","left","right","width"];function S(e,t){return t.map(r=>({style:e,prop:r,value:e.getPropertyValue(r),priority:e.getPropertyPriority(r)}))}function k(e){for(const{style:t,prop:r,value:o,priority:a}of e)o?t.setProperty(r,o,a):t.removeProperty(r)}function x(e,t=document){const r=d.get(t);if(r){r.owners.add(e);return}const o=t.body,a=t.documentElement,u=t.defaultView?.scrollY??0;d.set(t,{owners:new Set([e]),saved:[...S(o.style,D),...S(a.style,["overflow"])],scrollY:u}),o.style.position="fixed",o.style.top=`-${u}px`,o.style.left="0",o.style.right="0",o.style.width="100%",a.style.overflow="hidden"}function j(e,t=document){const r=d.get(t);!r||!r.owners.delete(e)||r.owners.size>0||(d.delete(t),k(r.saved),t.defaultView?.scrollTo(0,r.scrollY))}var L='"IBM Plex Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',N=`var(--ago-font, ${L})`,h={font:"--ago-font",radius:"--ago-radius",messageRadius:"--ago-message-radius",brand:"--ago-brand-color",brandText:"--ago-brand-text-color",headerBg:"--ago-header-background",headerText:"--ago-header-text-color",panelBg:"--ago-panel-background",messagesBg:"--ago-messages-background",text:"--ago-text-color",mutedText:"--ago-muted-text-color",border:"--ago-border-color",accent:"--ago-accent-color",agentBubbleBg:"--ago-agent-bubble-background"},M="var(--ago-brand-color, #03182f)",w="var(--ago-brand-text-color, #fff)",U="var(--ago-header-background, var(--ago-brand-color, #03182f))",G="var(--ago-header-text-color, #e8f0fe)",I="var(--ago-panel-background, #fff)",K="var(--ago-messages-background, #fbfbfb)",H="var(--ago-text-color, #30373e)",X="var(--ago-muted-text-color, #6b6d6f)",$="var(--ago-border-color, #dee3e8)",F="var(--ago-accent-color, #1b5fc4)",V="var(--ago-agent-bubble-background, #f1f3f5)",O="var(--ago-radius, 16px)",Y="var(--ago-message-radius, 16px)",z="var(--ago-message-radius, 20px)";function Q(e,t){if(t)for(const r of Object.keys(h)){const o=t[r];o!=null&&e.style.setProperty(h[r],o)}}function A(e,t){Object.assign(e.style,t)}function q(e={}){const t=document.createElement("div");return A(t,e),t}var _="ago-chat-widget-keyframes";function W(){if(typeof document>"u"||document.getElementById(_))return;const e=document.createElement("style");e.id=_,e.textContent="@keyframes ago-pulse { 0%, 80%, 100% { opacity: 0.3; transform: scale(0.8); } 40% { opacity: 1; transform: scale(1); } }@keyframes ago-spin { to { transform: rotate(360deg); } }",document.head.appendChild(e)}var Z="2147483000";function J(e,t="0px"){return e===void 0?t:typeof e=="number"?`${e}px`:e}function P(e){return`(max-width: ${e}px), (max-height: 500px) and (orientation: landscape)`}function ee(e={}){const t=e.breakpoint??768,r=e.peekHeight??152,o=J(e.bottomOffset),a=e.initialState??"peek",u=new Set;let l=a,f=!1;const c=typeof window<"u"&&typeof window.matchMedia=="function"?window.matchMedia(P(t)):void 0;let g=b();const B=y(!1,a);function T(n,i){if(!n)return{style:{},attrs:{role:null,"aria-modal":null,"aria-label":null}};const R={position:"fixed",left:"0",right:"0",bottom:o,zIndex:Z,display:"flex",flexDirection:"column",borderRadius:i==="full"?"0":`${O} ${O} 0 0`,paddingBottom:"env(safe-area-inset-bottom)"};return i==="full"?{style:{...R,top:"0",height:"auto",paddingTop:"env(safe-area-inset-top)"},attrs:{role:"dialog","aria-modal":"true",tabindex:"-1"}}:{style:{...R,top:"auto",minHeight:`calc(${r}px + env(safe-area-inset-bottom))`,height:"auto"},attrs:{role:null,"aria-modal":null,tabindex:"-1"}}}function y(n,i){return{compact:n,state:i,isModal:n&&i==="full",surface:T(n,i)}}function b(){return y(!!c?.matches,l)}function p(){g=b();for(const n of u)n()}function m(n,i){f||l===n||(l=n,p(),e.onStateChange?.(n,i))}function E(){if(!f){if(!c?.matches&&l!==a){l=a,p(),e.onStateChange?.(a,"breakpoint");return}p()}}let s=!1;function C(){s||!c||(c.addEventListener("change",E),s=!0,g=b())}function v(){!s||!c||(c.removeEventListener("change",E),s=!1)}return{subscribe(n){return u.add(n),u.size===1&&C(),()=>{u.delete(n),u.size===0&&v()}},getSnapshot:()=>g,getServerSnapshot:()=>B,expand:(n="api")=>m("full",n),collapse:(n="api")=>m("peek",n),toggle:(n="api")=>m(l==="full"?"peek":"full",n),destroy(){f||(f=!0,v(),u.clear())}}}Object.defineProperty(exports,"ACCENT_COLOR",{enumerable:!0,get:function(){return F}});Object.defineProperty(exports,"AGENT_BUBBLE_BACKGROUND",{enumerable:!0,get:function(){return V}});Object.defineProperty(exports,"BORDER_COLOR",{enumerable:!0,get:function(){return $}});Object.defineProperty(exports,"BRAND_COLOR",{enumerable:!0,get:function(){return M}});Object.defineProperty(exports,"BRAND_TEXT_COLOR",{enumerable:!0,get:function(){return w}});Object.defineProperty(exports,"FONT_VAR",{enumerable:!0,get:function(){return N}});Object.defineProperty(exports,"HEADER_BACKGROUND",{enumerable:!0,get:function(){return U}});Object.defineProperty(exports,"HEADER_TEXT_COLOR",{enumerable:!0,get:function(){return G}});Object.defineProperty(exports,"MESSAGES_BACKGROUND",{enumerable:!0,get:function(){return K}});Object.defineProperty(exports,"MESSAGE_RADIUS",{enumerable:!0,get:function(){return Y}});Object.defineProperty(exports,"MESSAGE_RADIUS_IMESSAGE",{enumerable:!0,get:function(){return z}});Object.defineProperty(exports,"MUTED_TEXT_COLOR",{enumerable:!0,get:function(){return X}});Object.defineProperty(exports,"PANEL_BACKGROUND",{enumerable:!0,get:function(){return I}});Object.defineProperty(exports,"RADIUS",{enumerable:!0,get:function(){return O}});Object.defineProperty(exports,"TEXT_COLOR",{enumerable:!0,get:function(){return H}});Object.defineProperty(exports,"applyTheme",{enumerable:!0,get:function(){return Q}});Object.defineProperty(exports,"compactMediaQuery",{enumerable:!0,get:function(){return P}});Object.defineProperty(exports,"createSheetController",{enumerable:!0,get:function(){return ee}});Object.defineProperty(exports,"css",{enumerable:!0,get:function(){return A}});Object.defineProperty(exports,"div",{enumerable:!0,get:function(){return q}});Object.defineProperty(exports,"ensureKeyframes",{enumerable:!0,get:function(){return W}});Object.defineProperty(exports,"lockBackgroundScroll",{enumerable:!0,get:function(){return x}});Object.defineProperty(exports,"unlockBackgroundScroll",{enumerable:!0,get:function(){return j}});