@useago/sdk 1.0.7 → 1.0.9

package/dist/createFormCollector-CFt1_QSL.js

@@ -0,0 +1,299 @@
+import { c as $ } from "./AgoClient-QcTtrN7u.js";
+function A(s, e) {
+  const a = e ? e.storage ?? (typeof localStorage < "u" ? localStorage : void 0) : void 0;
+  let n = s;
+  if (e && a) try {
+    const m = a.getItem(e.key);
+    m != null && (n = JSON.parse(m));
+  } catch {
+  }
+  const o = /* @__PURE__ */ new Set(), c = () => o.forEach((m) => m(n));
+  function b() {
+    if (e && a) try {
+      a.setItem(e.key, JSON.stringify(n));
+    } catch {
+    }
+  }
+  return {
+    get: () => n,
+    set: (m) => {
+      n = m, b(), c();
+    },
+    subscribe: (m) => (o.add(m), () => {
+      o.delete(m);
+    })
+  };
+}
+var P = /^[a-zA-Z0-9_-]{1,40}$/, W = (s) => s == null || s === "";
+function v(s, e) {
+  if ("anyOf" in s) return s.anyOf.some((c) => v(c, e));
+  if ("allOf" in s) return s.allOf.every((c) => v(c, e));
+  const a = e[s.property];
+  if (W(a)) return !1;
+  if (Array.isArray(s.value)) return s.value.some((c) => String(a) === String(c));
+  if (!s.op) return String(a) === String(s.value);
+  const n = Number(a), o = Number(s.value);
+  if (Number.isNaN(n) || Number.isNaN(o)) return !1;
+  switch (s.op) {
+    case ">=":
+      return n >= o;
+    case "<=":
+      return n <= o;
+    case ">":
+      return n > o;
+    case "<":
+      return n < o;
+    default:
+      return $.warn(`Unknown requiredWhen op "${s.op}"; treating as not required.`), !1;
+  }
+}
+function y(s, e) {
+  const a = s.properties ?? {}, n = /* @__PURE__ */ new Set();
+  for (const c of s.required ?? []) {
+    const b = a[c]?.requiredWhen;
+    (!b || v(b, e)) && n.add(c);
+  }
+  for (const [c, b] of Object.entries(a)) b.requiredWhen && v(b.requiredWhen, e) && n.add(c);
+  const o = [...n].filter((c) => W(e[c]));
+  return {
+    missing: o,
+    complete: o.length === 0
+  };
+}
+function J(s) {
+  const e = {};
+  for (const [a, n] of Object.entries(s.properties ?? {})) e[a] = {
+    type: n.type,
+    ...n.description != null && { description: n.description },
+    ...n.enum && { enum: n.enum },
+    ...n.default !== void 0 && { default: n.default }
+  };
+  return {
+    type: "object",
+    properties: e,
+    required: []
+  };
+}
+function R(s) {
+  const { name: e, description: a, schema: n } = s;
+  if (!P.test(e)) throw new Error(`Invalid form collector name "${e}": must match ${P} (it becomes the update_/submit_ function names).`);
+  const o = typeof s.submit == "string" ? s.submit ? {
+    via: "client",
+    url: s.submit
+  } : !1 : s.submit ?? !1;
+  s.autoSubmit === !0 && !o && $.warn(`FormCollector "${e}": autoSubmit is ignored because no submit target is configured.`);
+  const c = (s.autoSubmit ?? !0) && !!o, b = n.properties ?? {}, m = (t) => {
+    const r = {};
+    for (const [u, i] of Object.entries(t)) {
+      const l = b[u];
+      if (l)
+        if (i == null) r[u] = i;
+        else if (l.type === "number" || l.type === "integer") {
+          const d = typeof i == "number" ? i : Number(i);
+          r[u] = Number.isNaN(d) ? i : d;
+        } else l.type === "boolean" ? r[u] = typeof i == "boolean" ? i : i === "true" ? !0 : i === "false" ? !1 : !!i : r[u] = i;
+    }
+    return r;
+  }, S = s.initialValues ?? {}, f = A({
+    values: S,
+    submitted: !1
+  }), C = (t) => {
+    const r = f.get(), u = {
+      ...r,
+      values: {
+        ...r.values,
+        ...t
+      }
+    };
+    return f.set(u), u;
+  };
+  let h = null;
+  const k = (t, r) => {
+    h?.emitFormEvent("form:error", {
+      name: e,
+      values: t,
+      error: r
+    });
+  };
+  let p = null;
+  const j = async () => {
+    const { values: t } = f.get(), { complete: r, missing: u } = y(n, t);
+    if (!r) return {
+      ok: !1,
+      missing: u
+    };
+    if (!o) return {
+      ok: !1,
+      error: "No submit target configured for this form collector."
+    };
+    const i = t;
+    try {
+      let l;
+      if (o.via === "client") if ("handler" in o) l = await o.handler(i);
+      else {
+        const d = await fetch(o.url, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          credentials: "include",
+          body: JSON.stringify(i)
+        });
+        if (!d.ok) {
+          const x = `Submit failed: HTTP ${d.status}`;
+          return k(i, x), {
+            ok: !1,
+            error: x
+          };
+        }
+        l = await d.json().catch(() => {
+        });
+      }
+      else {
+        if (!h) return {
+          ok: !1,
+          error: "Backend submit requires install(client) (or useFormCollector) first."
+        };
+        l = await h.submitFormCollector(e, i);
+      }
+      return f.set({
+        ...f.get(),
+        submitted: !0,
+        submitResult: l
+      }), h?.emitFormEvent("form:submitted", {
+        name: e,
+        values: i,
+        result: l
+      }), {
+        ok: !0,
+        result: l
+      };
+    } catch (l) {
+      const d = l instanceof Error ? l.message : "Submit failed";
+      return $.error(`FormCollector "${e}" submit failed:`, l), k(i, d), {
+        ok: !1,
+        error: d
+      };
+    }
+  }, N = () => p || (p = (async () => {
+    try {
+      return await j();
+    } finally {
+      p = null;
+    }
+  })(), p), F = async () => {
+    if (!c || !o) return null;
+    const { values: t, submitted: r } = f.get();
+    return r || !y(n, t).complete ? null : N();
+  }, q = {
+    name: `update_${e}`,
+    description: `Fill or update fields of the "${e}" form. ${a} 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: J(n),
+    handler: async (t) => {
+      const r = C(m(t)), { missing: u } = y(n, r.values), i = await F();
+      return i ? i.ok ? {
+        ok: !0,
+        values: r.values,
+        missing: u,
+        submitted: !0
+      } : {
+        ok: !0,
+        values: r.values,
+        missing: u,
+        submitted: !1,
+        submitError: i.error
+      } : {
+        ok: !0,
+        values: r.values,
+        missing: u
+      };
+    }
+  }, g = [q];
+  o && !c && g.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: () => N()
+  });
+  const I = "client__", O = o ? `submit_${e}` : null, V = (t) => {
+    const r = t.functionName ?? t.toolName;
+    if (r)
+      return r.startsWith(I) ? r.slice(8) : r;
+  }, _ = (t) => {
+    let r = { ...S }, u = !1;
+    for (const i of t) {
+      const l = V(i);
+      l === q.name ? i.arguments && (r = {
+        ...r,
+        ...m(i.arguments)
+      }) : O && l === O && i.status?.toLowerCase() === "done" && (u = !0);
+    }
+    f.set({
+      values: r,
+      submitted: u
+    });
+  }, w = `form:${e}`, E = () => {
+    const { values: t, submitted: r } = f.get(), { missing: u, complete: i } = y(n, t), l = o ? 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}.` : "", d = 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: `${d} ${a} 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(n)}. Data collected so far: ${JSON.stringify(t)}. Call update_${e} with any fields the user provides; ask only for what is still missing.${l}`,
+      data: {
+        values: t,
+        missing: u,
+        complete: i,
+        submitted: r
+      }
+    };
+  }, T = (t) => {
+    _((t.messages ?? []).flatMap((r) => r.toolCalls ?? []));
+  };
+  return {
+    name: e,
+    store: f,
+    functions: g,
+    contextKey: w,
+    contextProvider: E,
+    install: (t) => {
+      h = t;
+      for (const u of g) t.register(u);
+      t.addDynamicContext(w, E);
+      const r = f.subscribe(() => t.notifyContextChanged());
+      return t.on("conversation:loaded", T), () => {
+        r();
+        for (const u of g) t.unregisterFunction(u.name);
+        t.removeDynamicContext(w), t.off("conversation:loaded", T), h === t && (h = null);
+      };
+    },
+    hydrate: _,
+    submit: N,
+    getValues: () => f.get().values,
+    setValues: (t) => {
+      C(m(t)), F();
+    },
+    reset: () => {
+      f.set({
+        values: S,
+        submitted: !1
+      });
+    },
+    getStatus: () => y(n, f.get().values)
+  };
+}
+async function L(s, e) {
+  const a = await s.getFormCollector(e.name);
+  return R({
+    name: a.name,
+    description: e.description ?? a.description,
+    schema: e.schema ?? a.schema,
+    submit: e.submit ?? a.submit,
+    initialValues: e.initialValues,
+    autoSubmit: e.autoSubmit ?? a.autoSubmit
+  });
+}
+export {
+  A as i,
+  y as n,
+  L as r,
+  R as t
+};

package/dist/devtools.d.cts

@@ -176,6 +176,7 @@ declare class AgoClient {
      * call it when their store updates so observers like the dev panel stay live.
      */
     notifyContextChanged(): void;
+    /* Excluded from this release type: emitFormEvent */
     /**
      * Enable automatic capture of the current browser page (URL + title).
      * Injected as a dynamic context entry named `browser-page`.
@@ -290,6 +291,27 @@ declare interface AgoClientEvents {
         result: unknown;
         error?: string;
     };
+    /**
+     * A form collector submitted successfully. `result` is the raw submit response
+     * (POST body / handler return value / backend relay result) — the third-party
+     * API's answer. `values` is the submitted field set, `name` the collector name.
+     */
+    "form:submitted": {
+        name: string;
+        values: Record<string, unknown>;
+        result: unknown;
+    };
+    /**
+     * A form collector submit was attempted and failed at the network/server level
+     * (HTTP non-2xx, or a thrown handler/fetch). `error` is the message. Validation
+     * pre-checks (missing required fields, no submit target) are NOT errors and do
+     * not fire this — they are returned to the caller as `{ ok: false }`.
+     */
+    "form:error": {
+        name: string;
+        values: Record<string, unknown>;
+        error: string;
+    };
     "connection:status": {
         connected: boolean;
     };
@@ -473,7 +495,7 @@ declare interface FormCollectorDefinition<V = Record<string, unknown>> {
 
 /**
  * Shape of a form's fields. Mirrors a client function's `parameters` (so the same
- * object feeds the store, the update function, and the dynamic context). Additionally allows the SDK-only per-field `requiredWhen`, which {@link toWireParameters} removes before the schema reaches the LLM.
+ * object feeds the store, the update function, and the dynamic context). Additionally allows the SDK-only per-field `requiredWhen`, which {@link toWireParameters} removes from the LLM tool's `parameters` (the full schema still reaches the agent via dynamic context).
  */
 declare interface FormCollectorSchema {
     type: "object";
@@ -490,17 +512,32 @@ declare interface FormField {
 }
 
 /**
- * A field's conditional-requiredness rule. The field becomes required exactly
- * when the controlling `property` matches `value` against the answers collected
- * so far:
+ * A field's conditional-requiredness rule: either a single {@link FormFieldLeafCondition}
+ * or a boolean combination of rules. `anyOf` is OR (true when any nested rule
+ * holds); `allOf` is AND (true when every nested rule holds). Both nest
+ * arbitrarily, so you can mix them, e.g.
+ * `{ anyOf: [{ property: "a", op: ">=", value: 1 }, { property: "b", value: "1" }] }`.
+ * An empty `anyOf` is never required; an empty `allOf` is always required.
+ *
+ * Stripped from the LLM tool's `parameters` (see {@link toWireParameters}), but the
+ * full schema, `requiredWhen` included, still reaches the agent via the dynamic
+ * context so it knows when each field becomes required.
+ */
+declare type FormFieldCondition = FormFieldLeafCondition | {
+    anyOf: FormFieldCondition[];
+} | {
+    allOf: FormFieldCondition[];
+};
+
+/**
+ * A single leaf comparison. The field it guards becomes required exactly when the
+ * controlling `property` matches `value` against the answers collected so far:
  * - a single `value`, no `op` — equality (compared as strings);
  * - a single `value` with `op` — numeric comparison (both sides coerced to numbers);
  * - an array `value`, no `op` — "one of": matches when the property equals any
  *   listed value.
- *
- * SDK-only — it is stripped from the schema before it reaches the LLM tool
  */
-declare interface FormFieldCondition {
+declare interface FormFieldLeafCondition {
     /** The controlling field whose value the rule tests. */
     property: string;
     /** Comparison operator; omitted means equality. Ignored when `value` is an array. */
@@ -521,7 +558,8 @@ declare interface FormFieldSchema {
     default?: unknown;
     /**
      * Makes the field required only while this condition holds. Drives the dynamic
-     * `missing` list; stripped before the LLM tool — see {@link toWireParameters}.
+     * `missing` list; stripped from the LLM tool's `parameters` (still sent to the
+     * agent via dynamic context). See {@link toWireParameters}.
      */
     requiredWhen?: FormFieldCondition;
 }

package/dist/devtools.d.ts

@@ -176,6 +176,7 @@ declare class AgoClient {
      * call it when their store updates so observers like the dev panel stay live.
      */
     notifyContextChanged(): void;
+    /* Excluded from this release type: emitFormEvent */
     /**
      * Enable automatic capture of the current browser page (URL + title).
      * Injected as a dynamic context entry named `browser-page`.
@@ -290,6 +291,27 @@ declare interface AgoClientEvents {
         result: unknown;
         error?: string;
     };
+    /**
+     * A form collector submitted successfully. `result` is the raw submit response
+     * (POST body / handler return value / backend relay result) — the third-party
+     * API's answer. `values` is the submitted field set, `name` the collector name.
+     */
+    "form:submitted": {
+        name: string;
+        values: Record<string, unknown>;
+        result: unknown;
+    };
+    /**
+     * A form collector submit was attempted and failed at the network/server level
+     * (HTTP non-2xx, or a thrown handler/fetch). `error` is the message. Validation
+     * pre-checks (missing required fields, no submit target) are NOT errors and do
+     * not fire this — they are returned to the caller as `{ ok: false }`.
+     */
+    "form:error": {
+        name: string;
+        values: Record<string, unknown>;
+        error: string;
+    };
     "connection:status": {
         connected: boolean;
     };
@@ -473,7 +495,7 @@ declare interface FormCollectorDefinition<V = Record<string, unknown>> {
 
 /**
  * Shape of a form's fields. Mirrors a client function's `parameters` (so the same
- * object feeds the store, the update function, and the dynamic context). Additionally allows the SDK-only per-field `requiredWhen`, which {@link toWireParameters} removes before the schema reaches the LLM.
+ * object feeds the store, the update function, and the dynamic context). Additionally allows the SDK-only per-field `requiredWhen`, which {@link toWireParameters} removes from the LLM tool's `parameters` (the full schema still reaches the agent via dynamic context).
  */
 declare interface FormCollectorSchema {
     type: "object";
@@ -490,17 +512,32 @@ declare interface FormField {
 }
 
 /**
- * A field's conditional-requiredness rule. The field becomes required exactly
- * when the controlling `property` matches `value` against the answers collected
- * so far:
+ * A field's conditional-requiredness rule: either a single {@link FormFieldLeafCondition}
+ * or a boolean combination of rules. `anyOf` is OR (true when any nested rule
+ * holds); `allOf` is AND (true when every nested rule holds). Both nest
+ * arbitrarily, so you can mix them, e.g.
+ * `{ anyOf: [{ property: "a", op: ">=", value: 1 }, { property: "b", value: "1" }] }`.
+ * An empty `anyOf` is never required; an empty `allOf` is always required.
+ *
+ * Stripped from the LLM tool's `parameters` (see {@link toWireParameters}), but the
+ * full schema, `requiredWhen` included, still reaches the agent via the dynamic
+ * context so it knows when each field becomes required.
+ */
+declare type FormFieldCondition = FormFieldLeafCondition | {
+    anyOf: FormFieldCondition[];
+} | {
+    allOf: FormFieldCondition[];
+};
+
+/**
+ * A single leaf comparison. The field it guards becomes required exactly when the
+ * controlling `property` matches `value` against the answers collected so far:
  * - a single `value`, no `op` — equality (compared as strings);
  * - a single `value` with `op` — numeric comparison (both sides coerced to numbers);
  * - an array `value`, no `op` — "one of": matches when the property equals any
  *   listed value.
- *
- * SDK-only — it is stripped from the schema before it reaches the LLM tool
  */
-declare interface FormFieldCondition {
+declare interface FormFieldLeafCondition {
     /** The controlling field whose value the rule tests. */
     property: string;
     /** Comparison operator; omitted means equality. Ignored when `value` is an array. */
@@ -521,7 +558,8 @@ declare interface FormFieldSchema {
     default?: unknown;
     /**
      * Makes the field required only while this condition holds. Drives the dynamic
-     * `missing` list; stripped before the LLM tool — see {@link toWireParameters}.
+     * `missing` list; stripped from the LLM tool's `parameters` (still sent to the
+     * agent via dynamic context). See {@link toWireParameters}.
      */
     requiredWhen?: FormFieldCondition;
 }

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("./AgoClient--y10UXUV.cjs"),m=require("./createFormCollector-DWzGKDwO.cjs"),p=require("./createConversationSession-BuMXp0Ia.cjs"),w=require("./createMockClient-zHQ0cjUH.cjs");require("./testing.cjs");const g=require("./functions-Djnq-JAo.cjs");function h(e){return e}function E(e,o){return e.on("message:complete",o),()=>e.off("message:complete",o)}function S(e,o){return e.on("message:chunk",o),()=>e.off("message:chunk",o)}function y(e,o){return e.on("message:start",o),()=>e.off("message:start",o)}function v(e,o){return e.on("message:error",o),()=>e.off("message:error",o)}function b(e,o){return e.on("toolCall:received",o),()=>e.off("toolCall:received",o)}function F(e,o){return e.on("function:invoke",o),()=>e.off("function:invoke",o)}async function*M(e,o,l){const a=[];let r=null,s=!1;const c=i=>{a.push(i),r?.()},f=i=>c({type:"start",data:i}),t=i=>c({type:"chunk",data:i}),u=i=>{c({type:"complete",data:i}),s=!0,r?.()},d=i=>{c({type:"error",data:i}),s=!0,r?.()},C=i=>c({type:"toolCall",data:i});e.on("message:start",f),e.on("message:chunk",t),e.on("message:complete",u),e.on("message:error",d),e.on("toolCall:received",C),e.sendMessage(o,l).catch(()=>{s=!0,r?.()});try{for(;!s||a.length>0;)a.length>0?yield a.shift():(await new Promise(i=>{r=i}),r=null)}finally{e.off("message:start",f),e.off("message:chunk",t),e.off("message:complete",u),e.off("message:error",d),e.off("toolCall:received",C)}}function A(e){let o,l,a,r,s,c;if(typeof window<"u"&&window.AGO){const t=window.AGO;o=t.basepath,l=t.widgetId,a=t.agent||t.defaultAgent,r=t.permission,s=t.email,c=t.jwt}if(typeof document<"u"){const t=u=>document.querySelector(`meta[name="${u}"]`)?.getAttribute("content")||void 0;o=o||t("ago-base-url"),l=l||t("ago-widget-id"),a=a||t("ago-agent")||t("ago-agent-id"),r=r||t("ago-permission"),s=s||t("ago-user-email")}if(typeof document<"u"){const t=[document.body,...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);for(const u of t)u&&(o=o||u.getAttribute("data-ago-base-url")||void 0,l=l||u.getAttribute("data-ago-widget-id")||void 0,a=a||u.getAttribute("data-ago-agent")||u.getAttribute("data-ago-agent-id")||void 0,r=r||u.getAttribute("data-ago-permission")||void 0,s=s||u.getAttribute("data-ago-user-email")||void 0)}o=e?.baseUrl||o,l=e?.widgetId||l,a=e?.agent||e?.defaultAgentId||a,r=e?.permission||r,s=e?.userEmail||s,c=e?.userJwt||c;const f=e?.debug;return o?{baseUrl:o,widgetId:l,agent:a,permission:r,userEmail:s,userJwt:c,debug:f}:null}function k(e){const o=A(e);if(!o)throw new n.AgoError('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 n.AgoClient(o)}function q(e,o){return{...e,handler:o}}exports.AgoApiError=n.AgoApiError;exports.AgoClient=n.AgoClient;exports.AgoError=n.AgoError;exports.AgoFunctionError=n.AgoFunctionError;exports.AgoNetworkError=n.AgoNetworkError;exports.AgoStreamError=n.AgoStreamError;exports.ClientContextRegistry=n.ClientContextRegistry;exports.EventEmitter=n.EventEmitter;exports.FunctionRegistry=n.FunctionRegistry;exports.SSEHandler=n.SSEHandler;exports.autoDetectConfig=A;exports.copyToClipboard=g.copyToClipboard;exports.createAgo=k;exports.createConversationSession=p.createConversationSession;exports.createFormCollector=m.createFormCollector;exports.createMessageStream=M;exports.createMockClient=w.createMockClient;exports.createStore=m.createStore;exports.defineFunction=h;exports.deriveFormStatus=m.deriveFormStatus;exports.getLocalStorage=g.getLocalStorage;exports.getUserLocation=g.getUserLocation;exports.highlightElement=g.highlightElement;exports.isStreamNetworkError=n.isStreamNetworkError;exports.loadFormCollector=m.loadFormCollector;exports.logger=n.logger;exports.onFunctionInvoke=F;exports.onMessage=E;exports.onMessageChunk=S;exports.onMessageError=v;exports.onMessageStart=y;exports.onToolCall=b;exports.openUrl=g.openUrl;exports.scrollToElement=g.scrollToElement;exports.setLocalStorage=g.setLocalStorage;exports.setTheme=g.setTheme;exports.showConfirmDialog=g.showConfirmDialog;exports.showNotification=g.showNotification;exports.showToast=g.showToast;exports.submitForm=g.submitForm;exports.trackEvent=g.trackEvent;exports.validateConfig=n.validateConfig;exports.withHandler=q;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("./AgoClient-B3-WGVne.cjs"),f=require("./createFormCollector-BI3DXaew.cjs"),p=require("./createConversationSession-C0diFTUk.cjs"),w=require("./createMockClient-zHQ0cjUH.cjs");require("./testing.cjs");const g=require("./functions-Djnq-JAo.cjs");function h(e){return e}function E(e,o){return e.on("message:complete",o),()=>e.off("message:complete",o)}function S(e,o){return e.on("message:chunk",o),()=>e.off("message:chunk",o)}function y(e,o){return e.on("message:start",o),()=>e.off("message:start",o)}function b(e,o){return e.on("message:error",o),()=>e.off("message:error",o)}function F(e,o){return e.on("toolCall:received",o),()=>e.off("toolCall:received",o)}function v(e,o){return e.on("form:submitted",o),()=>e.off("form:submitted",o)}function M(e,o){return e.on("form:error",o),()=>e.off("form:error",o)}function q(e,o){return e.on("function:invoke",o),()=>e.off("function:invoke",o)}async function*k(e,o,l){const a=[];let r=null,s=!1;const m=i=>{a.push(i),r?.()},c=i=>m({type:"start",data:i}),t=i=>m({type:"chunk",data:i}),u=i=>{m({type:"complete",data:i}),s=!0,r?.()},d=i=>{m({type:"error",data:i}),s=!0,r?.()},C=i=>m({type:"toolCall",data:i});e.on("message:start",c),e.on("message:chunk",t),e.on("message:complete",u),e.on("message:error",d),e.on("toolCall:received",C),e.sendMessage(o,l).catch(()=>{s=!0,r?.()});try{for(;!s||a.length>0;)a.length>0?yield a.shift():(await new Promise(i=>{r=i}),r=null)}finally{e.off("message:start",c),e.off("message:chunk",t),e.off("message:complete",u),e.off("message:error",d),e.off("toolCall:received",C)}}function A(e){let o,l,a,r,s,m;if(typeof window<"u"&&window.AGO){const t=window.AGO;o=t.basepath,l=t.widgetId,a=t.agent||t.defaultAgent,r=t.permission,s=t.email,m=t.jwt}if(typeof document<"u"){const t=u=>document.querySelector(`meta[name="${u}"]`)?.getAttribute("content")||void 0;o=o||t("ago-base-url"),l=l||t("ago-widget-id"),a=a||t("ago-agent")||t("ago-agent-id"),r=r||t("ago-permission"),s=s||t("ago-user-email")}if(typeof document<"u"){const t=[document.body,...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);for(const u of t)u&&(o=o||u.getAttribute("data-ago-base-url")||void 0,l=l||u.getAttribute("data-ago-widget-id")||void 0,a=a||u.getAttribute("data-ago-agent")||u.getAttribute("data-ago-agent-id")||void 0,r=r||u.getAttribute("data-ago-permission")||void 0,s=s||u.getAttribute("data-ago-user-email")||void 0)}o=e?.baseUrl||o,l=e?.widgetId||l,a=e?.agent||e?.defaultAgentId||a,r=e?.permission||r,s=e?.userEmail||s,m=e?.userJwt||m;const c=e?.debug;return o?{baseUrl:o,widgetId:l,agent:a,permission:r,userEmail:s,userJwt:m,debug:c}:null}function T(e){const o=A(e);if(!o)throw new n.AgoError('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 n.AgoClient(o)}function _(e,o){return{...e,handler:o}}exports.AgoApiError=n.AgoApiError;exports.AgoClient=n.AgoClient;exports.AgoError=n.AgoError;exports.AgoFunctionError=n.AgoFunctionError;exports.AgoNetworkError=n.AgoNetworkError;exports.AgoStreamError=n.AgoStreamError;exports.ClientContextRegistry=n.ClientContextRegistry;exports.EventEmitter=n.EventEmitter;exports.FunctionRegistry=n.FunctionRegistry;exports.SSEHandler=n.SSEHandler;exports.autoDetectConfig=A;exports.copyToClipboard=g.copyToClipboard;exports.createAgo=T;exports.createConversationSession=p.createConversationSession;exports.createFormCollector=f.createFormCollector;exports.createMessageStream=k;exports.createMockClient=w.createMockClient;exports.createStore=f.createStore;exports.defineFunction=h;exports.deriveFormStatus=f.deriveFormStatus;exports.getLocalStorage=g.getLocalStorage;exports.getUserLocation=g.getUserLocation;exports.highlightElement=g.highlightElement;exports.isStreamNetworkError=n.isStreamNetworkError;exports.loadFormCollector=f.loadFormCollector;exports.logger=n.logger;exports.onFormError=M;exports.onFormSubmitted=v;exports.onFunctionInvoke=q;exports.onMessage=E;exports.onMessageChunk=S;exports.onMessageError=b;exports.onMessageStart=y;exports.onToolCall=F;exports.openUrl=g.openUrl;exports.scrollToElement=g.scrollToElement;exports.setLocalStorage=g.setLocalStorage;exports.setTheme=g.setTheme;exports.showConfirmDialog=g.showConfirmDialog;exports.showNotification=g.showNotification;exports.showToast=g.showToast;exports.submitForm=g.submitForm;exports.trackEvent=g.trackEvent;exports.validateConfig=n.validateConfig;exports.withHandler=_;

package/dist/index.d.cts

@@ -187,6 +187,7 @@ export declare class AgoClient {
      * call it when their store updates so observers like the dev panel stay live.
      */
     notifyContextChanged(): void;
+    /* Excluded from this release type: emitFormEvent */
     /**
      * Enable automatic capture of the current browser page (URL + title).
      * Injected as a dynamic context entry named `browser-page`.
@@ -301,6 +302,27 @@ export declare interface AgoClientEvents {
         result: unknown;
         error?: string;
     };
+    /**
+     * A form collector submitted successfully. `result` is the raw submit response
+     * (POST body / handler return value / backend relay result) — the third-party
+     * API's answer. `values` is the submitted field set, `name` the collector name.
+     */
+    "form:submitted": {
+        name: string;
+        values: Record<string, unknown>;
+        result: unknown;
+    };
+    /**
+     * A form collector submit was attempted and failed at the network/server level
+     * (HTTP non-2xx, or a thrown handler/fetch). `error` is the message. Validation
+     * pre-checks (missing required fields, no submit target) are NOT errors and do
+     * not fire this — they are returned to the caller as `{ ok: false }`.
+     */
+    "form:error": {
+        name: string;
+        values: Record<string, unknown>;
+        error: string;
+    };
     "connection:status": {
         connected: boolean;
     };
@@ -913,7 +935,7 @@ export declare interface FormCollectorDefinition<V = Record<string, unknown>> {
 
 /**
  * Shape of a form's fields. Mirrors a client function's `parameters` (so the same
- * object feeds the store, the update function, and the dynamic context). Additionally allows the SDK-only per-field `requiredWhen`, which {@link toWireParameters} removes before the schema reaches the LLM.
+ * object feeds the store, the update function, and the dynamic context). Additionally allows the SDK-only per-field `requiredWhen`, which {@link toWireParameters} removes from the LLM tool's `parameters` (the full schema still reaches the agent via dynamic context).
  */
 export declare interface FormCollectorSchema {
     type: "object";
@@ -953,17 +975,32 @@ export declare interface FormField {
 }
 
 /**
- * A field's conditional-requiredness rule. The field becomes required exactly
- * when the controlling `property` matches `value` against the answers collected
- * so far:
+ * A field's conditional-requiredness rule: either a single {@link FormFieldLeafCondition}
+ * or a boolean combination of rules. `anyOf` is OR (true when any nested rule
+ * holds); `allOf` is AND (true when every nested rule holds). Both nest
+ * arbitrarily, so you can mix them, e.g.
+ * `{ anyOf: [{ property: "a", op: ">=", value: 1 }, { property: "b", value: "1" }] }`.
+ * An empty `anyOf` is never required; an empty `allOf` is always required.
+ *
+ * Stripped from the LLM tool's `parameters` (see {@link toWireParameters}), but the
+ * full schema, `requiredWhen` included, still reaches the agent via the dynamic
+ * context so it knows when each field becomes required.
+ */
+export declare type FormFieldCondition = FormFieldLeafCondition | {
+    anyOf: FormFieldCondition[];
+} | {
+    allOf: FormFieldCondition[];
+};
+
+/**
+ * A single leaf comparison. The field it guards becomes required exactly when the
+ * controlling `property` matches `value` against the answers collected so far:
  * - a single `value`, no `op` — equality (compared as strings);
  * - a single `value` with `op` — numeric comparison (both sides coerced to numbers);
  * - an array `value`, no `op` — "one of": matches when the property equals any
  *   listed value.
- *
- * SDK-only — it is stripped from the schema before it reaches the LLM tool
  */
-declare interface FormFieldCondition {
+export declare interface FormFieldLeafCondition {
     /** The controlling field whose value the rule tests. */
     property: string;
     /** Comparison operator; omitted means equality. Ignored when `value` is an array. */
@@ -977,14 +1014,15 @@ declare interface FormFieldCondition {
 }
 
 /** A single field's schema: the wire-legal keys plus the SDK-only `requiredWhen`. */
-declare interface FormFieldSchema {
+export declare interface FormFieldSchema {
     type: string;
     description?: string;
     enum?: string[];
     default?: unknown;
     /**
      * Makes the field required only while this condition holds. Drives the dynamic
-     * `missing` list; stripped before the LLM tool — see {@link toWireParameters}.
+     * `missing` list; stripped from the LLM tool's `parameters` (still sent to the
+     * agent via dynamic context). See {@link toWireParameters}.
      */
     requiredWhen?: FormFieldCondition;
 }
@@ -1162,6 +1200,23 @@ export declare interface MockAgoClientOptions {
 
 declare type MockFn = (...args: any[]) => any;
 
+/**
+ * Subscribe to failed form collector submissions (network/server failures).
+ */
+export declare function onFormError(client: AgoClient, callback: (data: AgoClientEvents["form:error"]) => void): () => void;
+
+/**
+ * Subscribe to successful form collector submissions. `result` is the submit
+ * response (the third-party API's answer). Returns an unsubscribe function.
+ *
+ * ```ts
+ * const unsub = onFormSubmitted(client, ({ name, result }) => {
+ *   console.log(name, "submitted", result);
+ * });
+ * ```
+ */
+export declare function onFormSubmitted(client: AgoClient, callback: (data: AgoClientEvents["form:submitted"]) => void): () => void;
+
 /**
  * Subscribe to client function invocations.
  */