@useago/sdk 1.13.2 → 1.14.0

package/llms-full.txt

@@ -1830,11 +1830,28 @@ client.registerFunction({
   description: "The flights currently on screen, after filtering.",
   parameters: { type: "object", properties: {} },
   handler: () => visibleFlights(),
-  // Optional, WebMCP only: MCP behavior hints.
+  // Optional, WebMCP only: tool annotations.
   webmcp: { annotations: { readOnlyHint: true } },
 });
 ```
 
+The optional `webmcp.annotations` fields describe the tool to browser agents:
+
+| Annotation | Meaning when `true` |
+| --- | --- |
+| `readOnlyHint` | Only reads data and does not change state. |
+| `untrustedContentHint` | Returns content untrusted by the tool author, such as customer reviews. |
+| `consequentialHint` | Has significant, real-world, or irreversible effects, such as purchasing a flight. |
+| `debugging` | Is intended for debugging and developer tooling. |
+
+All four default to `false` in WebMCP. For example, a purchase tool can set
+`webmcp: { annotations: { consequentialHint: true } }`, and a diagnostic tool
+can set `webmcp: { annotations: { debugging: true } }`.
+
+The SDK forwards these annotations to the browser without changing AGO's
+in-app agent behavior. `consequentialHint` and `requiresApproval` are independent:
+neither sets the other, and annotations do not enforce confirmation dialogs.
+
 In React it is a prop:
 
 ```tsx
@@ -2192,6 +2209,7 @@ const final = await client.waitFor("message:complete", { timeout: 10_000 });
 | `function:result` | `{ invocationId, result, error? }` |
 | `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) |
 | `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) |
+| `form:submitting` | `{ name, values }`: validated submission is about to start |
 | `form:submitted` | `{ name, values, result }`: a form collector submitted successfully; `result` is the submit response (the third-party API's answer) |
 | `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 |
 | `connection:status` | `{ connected }` |
@@ -2232,6 +2250,7 @@ onMessage(client, (msg) => console.log("complete:", msg.content));
 | `onMessageError(client, cb)` | `message:error` |
 | `onToolCall(client, cb)` | `toolCall:received` |
 | `onFunctionInvoke(client, cb)` | `function:invoke` |
+| `onFormSubmitting(client, cb)` | `form:submitting` |
 | `onFormSubmitted(client, cb)` | `form:submitted` |
 | `onFormError(client, cb)` | `form:error` |
 
@@ -2385,6 +2404,25 @@ interface AgoConfig {
 
 ---
 
+## Ticket-form language
+
+```ts
+import { AgoClient } from '@useago/sdk';
+
+const client = new AgoClient({
+  baseUrl: 'https://playground.api.useago.com',
+  language: 'fr',
+});
+const config = await client.getConfig();
+client.updateConfig({ language: 'pt-PT' });
+```
+
+The SDK includes English, French, German, Spanish, Italian and Brazilian Portuguese UI wording. Regional tags use the corresponding base-language UI. Omitted, `null` or unsupported languages use English; `undefined` leaves the current setting unchanged.
+
+`getConfig()` requests translated form content with `ticket_form_i18n=1` and `language`. Supported regional tags are preserved. Each string tries the exact locale, base language, preferred region (`en-GB`, `fr-FR` or `pt-PT`), then other matching regions alphabetically. It repeats that sequence for the tenant default before using the original text. Translated labels do not change submitted values.
+
+Change language with `updateConfig()`. SDK UI components preserve drafts, attachments and submission state while loading translated forms; a failed switch keeps the previous wording. Headless integrations must call `getConfig()` again and update their own UI. Explicit wording overrides remain in effect.
+
 ## Debug logging
 
 `debug: true` turns on the SDK's internal logger. While enabled, the client
@@ -2537,9 +2575,10 @@ const sources = conversation.messages?.flatMap((message) => message.sources ?? [
 `createAgo({ language: "fr" })` also accepts an explicit locale when your API
 configuration is detected from the page.
 
-This header does not force the agent's reply language or translate your UI text.
-Continue passing translated labels, placeholders and welcome text from your
-application's translations.
+The language setting also selects the SDK's standard UI wording, as described in
+[ticket-form language](#ticket-form-language). It does not force the agent's reply
+language. Host-authored welcome text and explicit label overrides remain your
+application's responsibility.
 
 ### User and ticket metadata
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useago/sdk",
-  "version": "1.13.2",
+  "version": "1.14.0",
   "description": "Create In-APP AI agents that answers question and performs actions. Works with React, Vue, Angular and vanilla JS/TS.",
   "type": "module",
   "sideEffects": false,

package/dist/createFormCollector-Cq7HWjtU.cjs

@@ -1 +0,0 @@
-const C=require("./types-DNr6XEwI.cjs");var W=/^[a-zA-Z0-9_-]{1,40}$/,V=n=>n==null||n==="";function S(n,e){if("anyOf"in n)return n.anyOf.some(c=>S(c,e));if("allOf"in n)return n.allOf.every(c=>S(c,e));const l=e[n.property];if(V(l))return!1;if(Array.isArray(n.value))return n.value.some(c=>String(l)===String(c));if(!n.op)return String(l)===String(n.value);const i=Number(l),a=Number(n.value);if(Number.isNaN(i)||Number.isNaN(a))return!1;switch(n.op){case">=":return i>=a;case"<=":return i<=a;case">":return i>a;case"<":return i<a;default:return C.logger.warn(`Unknown requiredWhen op "${n.op}"; treating as not required.`),!1}}function h(n,e){const l=n.properties??{},i=new Set;for(const c of n.required??[]){const d=l[c]?.requiredWhen;(!d||S(d,e))&&i.add(c)}for(const[c,d]of Object.entries(l))d.requiredWhen&&S(d.requiredWhen,e)&&i.add(c);const a=[...i].filter(c=>V(e[c]));return{missing:a,complete:a.length===0}}function B(n){const e={};for(const[l,i]of Object.entries(n.properties??{}))e[l]={type:i.type,...i.description!=null&&{description:i.description},...i.enum&&{enum:i.enum},...i.default!==void 0&&{default:i.default}};return{type:"object",properties:e,required:[]}}function A(n){const{name:e,description:l,schema:i}=n;if(!W.test(e))throw new Error(`Invalid form collector name "${e}": must match ${W} (it becomes the update_/submit_ function names).`);const a=typeof n.submit=="string"?n.submit?{via:"client",url:n.submit}:!1:n.submit??!1;n.autoSubmit===!0&&!a&&C.logger.warn(`FormCollector "${e}": autoSubmit is ignored because no submit target is configured.`);const c=(n.autoSubmit??!0)&&!!a,d=i.properties??{},$=t=>{const r={};for(const[o,s]of Object.entries(t)){const u=d[o];if(u)if(s==null)r[o]=s;else if(u.type==="number"||u.type==="integer"){const f=typeof s=="number"?s:Number(s);r[o]=Number.isNaN(f)?s:f}else u.type==="boolean"?r[o]=typeof s=="boolean"?s:s==="true"?!0:s==="false"?!1:!!s:r[o]=s}return r},N=n.initialValues??{},m=C.createStore({values:N,submitted:!1}),w=t=>{const r=m.get(),o={...r,values:{...r.values,...t}};return m.set(o),o};let b=null;const k=(t,r)=>{b?.emitFormEvent("form:error",{name:e,values:t,error:r})};let p=null;const I=async()=>{const{values:t}=m.get(),{complete:r,missing:o}=h(i,t);if(!r)return{ok:!1,missing:o};if(!a)return{ok:!1,error:"No submit target configured for this form collector."};const s=t;try{let u;if(a.via==="client")if("handler"in a)u=await a.handler(s);else{const f=await fetch(a.url,{method:"POST",headers:{"Content-Type":"application/json"},credentials:"include",body:JSON.stringify(s)});if(!f.ok){const j=`Submit failed: HTTP ${f.status}`;return k(s,j),{ok:!1,error:j}}u=await f.json().catch(()=>{})}else{if(!b)return{ok:!1,error:"Backend submit requires install(client) (or useFormCollector) first."};u=await b.submitFormCollector(e,s)}return m.set({...m.get(),submitted:!0,submitResult:u}),b?.emitFormEvent("form:submitted",{name:e,values:s,result:u}),{ok:!0,result:u}}catch(u){const f=u instanceof Error?u.message:"Submit failed";return C.logger.error(`FormCollector "${e}" submit failed:`,u),k(s,f),{ok:!1,error:f}}},F=()=>p||(p=(async()=>{try{return await I()}finally{p=null}})(),p),q=async()=>{if(!c||!a)return null;const{values:t,submitted:r}=m.get();return r||!h(i,t).complete?null:F()},O={name:`update_${e}`,description:`Fill or update fields of the "${e}" form. ${l} Pass any subset of fields; call it repeatedly to fill the form as the user provides information. Returns the current values and which required fields are still missing.`,parameters:B(i),handler:async t=>{const r=w($(t)),{missing:o}=h(i,r.values),s=await q();return s?s.ok?{ok:!0,values:r.values,missing:o,submitted:!0}:{ok:!0,values:r.values,missing:o,submitted:!1,submitError:s.error}:{ok:!0,values:r.values,missing:o}}},y=[O];a&&!c&&y.push({name:`submit_${e}`,description:`Submit the completed "${e}" form. Only call this once every required field is collected and the user has confirmed. If fields are missing it returns them instead of submitting.`,parameters:{type:"object",properties:{}},handler:()=>F()});const D="client__",_=a?`submit_${e}`:null,R=t=>{const r=t.functionName??t.toolName;if(r)return r.startsWith(D)?r.slice(8):r},x=t=>{let r={...N},o=!1;for(const s of t){const u=R(s);u===O.name?s.arguments&&(r={...r,...$(s.arguments)}):_&&u===_&&s.status?.toLowerCase()==="done"&&(o=!0)}m.set({values:r,submitted:o})},g=`form:${e}`,v=`${g}:definition`,P=()=>({name:`Form definition: ${e}`,description:`${l} Some fields are conditionally required; the requiredWhen field in the schema tells you when each becomes required. The form schema is the following: ${JSON.stringify(i)}.`,stable:!0}),T=()=>{const{values:t,submitted:r}=m.get(),{missing:o,complete:s}=h(i,t),u=a?c?" The form is submitted automatically as soon as every required field is filled, so there is no submit function to call.":` When nothing is missing and the user confirms, call submit_${e}.`:"",f=r?`The "${e}" form has been submitted.`:`You are currently collecting information from the user to fill the "${e}" form.`;return{name:`Form: ${e}`,description:`${f} The form's schema and field requirements are in the "${v}" client context. Call update_${e} with any fields the user provides; ask only for what is still missing.${u}`,data:{values:t,missing:o,complete:s,submitted:r}}},E=t=>{x((t.messages??[]).flatMap(r=>r.toolCalls??[]))};return{name:e,store:m,functions:y,contextKey:g,contextProvider:T,definitionContextKey:v,definitionContextProvider:P,install:t=>{b=t;for(const o of y)t.register(o);t.addDynamicContext(v,P),t.addDynamicContext(g,T);const r=m.subscribe(()=>t.notifyContextChanged());return t.on("conversation:loaded",E),()=>{r();for(const o of y)t.unregisterFunction(o.name);t.removeDynamicContext(g),t.removeDynamicContext(v),t.off("conversation:loaded",E),b===t&&(b=null)}},hydrate:x,submit:F,getValues:()=>m.get().values,setValues:t=>{w($(t)),q()},reset:()=>{m.set({values:N,submitted:!1})},getStatus:()=>h(i,m.get().values)}}async function L(n,e){const l=await n.getFormCollector(e.name);return A({name:l.name,description:e.description??l.description,schema:e.schema??l.schema,submit:e.submit??l.submit,initialValues:e.initialValues,autoSubmit:e.autoSubmit??l.autoSubmit})}Object.defineProperty(exports,"createFormCollector",{enumerable:!0,get:function(){return A}});Object.defineProperty(exports,"deriveFormStatus",{enumerable:!0,get:function(){return h}});Object.defineProperty(exports,"loadFormCollector",{enumerable:!0,get:function(){return L}});