@useago/sdk 0.4.7 → 1.0.1

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 (39) hide show
  1. package/CHANGELOG.md +98 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +10 -0
  4. package/README.md +107 -70
  5. package/dist/{AgoClient-CPqPT5s6.cjs → AgoClient-0x2Du_62.cjs} +1 -1
  6. package/dist/{AgoClient-BrYhSO5M.js → AgoClient-CZYNL25R.js} +29 -20
  7. package/dist/angular.cjs +1 -1
  8. package/dist/angular.d.cts +89 -0
  9. package/dist/angular.d.ts +89 -0
  10. package/dist/angular.js +1 -1
  11. package/dist/{createConversationSession-CGRO0bs2.cjs → createConversationSession-BLZvXMmM.cjs} +1 -1
  12. package/dist/{createConversationSession-Dmqd80DX.js → createConversationSession-Bmqj2rSS.js} +1 -1
  13. package/dist/createFormCollector-Bk0DRhUf.js +257 -0
  14. package/dist/createFormCollector-Ca8wRrxc.cjs +1 -0
  15. package/dist/devtools.d.cts +89 -0
  16. package/dist/devtools.d.ts +89 -0
  17. package/dist/index.cjs +1 -1
  18. package/dist/index.d.cts +47 -0
  19. package/dist/index.d.ts +47 -0
  20. package/dist/index.js +70 -68
  21. package/dist/react.cjs +23 -23
  22. package/dist/react.d.cts +74 -23
  23. package/dist/react.d.ts +74 -23
  24. package/dist/react.js +2154 -2075
  25. package/dist/testing.cjs +1 -0
  26. package/dist/testing.d.cts +571 -0
  27. package/dist/testing.d.ts +571 -0
  28. package/dist/testing.js +4 -0
  29. package/dist/vue.cjs +1 -1
  30. package/dist/vue.d.cts +89 -0
  31. package/dist/vue.d.ts +89 -0
  32. package/dist/vue.js +1 -1
  33. package/dist/widget.cjs +4 -4
  34. package/dist/widget.d.cts +74 -5
  35. package/dist/widget.d.ts +74 -5
  36. package/dist/widget.js +410 -317
  37. package/package.json +30 -9
  38. package/dist/createFormCollector-CPS2phYq.js +0 -245
  39. package/dist/createFormCollector-DaWZsBsI.cjs +0 -1
@@ -53,6 +53,13 @@ declare class AgoClient {
53
53
  * Reject a tool call
54
54
  */
55
55
  rejectToolCall(toolCallId: string): Promise<void>;
56
+ /**
57
+ * Fetch a backend-stored form collector definition by name (the single source
58
+ * of truth for the form's description, schema, and submit target). Used by
59
+ * `loadFormCollector` / the name-only form of `useFormCollector` so the schema
60
+ * lives in the backend instead of being hardcoded in client code.
61
+ */
62
+ getFormCollector(name: string): Promise<FormCollectorDefinition>;
56
63
  /**
57
64
  * Relay a completed form collector's values to a server-configured destination.
58
65
  *
@@ -399,6 +406,30 @@ export declare interface DevPanelOptions {
399
406
  */
400
407
  declare type DynamicContextProvider = () => ContextEntry | null | undefined;
401
408
 
409
+ /**
410
+ * The backend-stored shape returned by `GET /api/sdk/v1/forms/{name}` (see
411
+ * {@link AgoClient.getFormCollector}). Mirrors the persistable subset of
412
+ * {@link CreateFormCollectorOptions}: the `submit` here is never the client-only
413
+ * `handler` variant (a function can't be stored server-side).
414
+ */
415
+ declare interface FormCollectorDefinition<V = Record<string, unknown>> {
416
+ name: string;
417
+ description: string;
418
+ schema: FormCollectorSchema;
419
+ /** Server-stored submit target, if any. Absent means collect-only. */
420
+ submit?: SubmitConfig<V>;
421
+ }
422
+
423
+ /**
424
+ * Shape of a form's fields. Mirrors a client function's `parameters` (so the same
425
+ * 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.
426
+ */
427
+ declare interface FormCollectorSchema {
428
+ type: "object";
429
+ properties: Record<string, FormFieldSchema>;
430
+ required?: string[];
431
+ }
432
+
402
433
  declare interface FormField {
403
434
  type: "string" | "number" | "boolean" | "array";
404
435
  title?: string;
@@ -407,6 +438,43 @@ declare interface FormField {
407
438
  default?: unknown;
408
439
  }
409
440
 
441
+ /**
442
+ * A field's conditional-requiredness rule. The field becomes required exactly
443
+ * when the controlling `property` matches `value` against the answers collected
444
+ * so far:
445
+ * - a single `value`, no `op` — equality (compared as strings);
446
+ * - a single `value` with `op` — numeric comparison (both sides coerced to numbers);
447
+ * - an array `value`, no `op` — "one of": matches when the property equals any
448
+ * listed value.
449
+ *
450
+ * SDK-only — it is stripped from the schema before it reaches the LLM tool
451
+ */
452
+ declare interface FormFieldCondition {
453
+ /** The controlling field whose value the rule tests. */
454
+ property: string;
455
+ /** Comparison operator; omitted means equality. Ignored when `value` is an array. */
456
+ op?: ">=" | "<=" | ">" | "<";
457
+ /**
458
+ * The value(s) to test the controlling field against. A single value is an
459
+ * equality (or, with `op`, a numeric comparison); an array is an "is one of"
460
+ * membership test, e.g. `value: ["1", "2", "3"]`.
461
+ */
462
+ value: string | number | Array<string | number>;
463
+ }
464
+
465
+ /** A single field's schema: the wire-legal keys plus the SDK-only `requiredWhen`. */
466
+ declare interface FormFieldSchema {
467
+ type: string;
468
+ description?: string;
469
+ enum?: string[];
470
+ default?: unknown;
471
+ /**
472
+ * Makes the field required only while this condition holds. Drives the dynamic
473
+ * `missing` list; stripped before the LLM tool — see {@link toWireParameters}.
474
+ */
475
+ requiredWhen?: FormFieldCondition;
476
+ }
477
+
410
478
  /**
411
479
  * Form schema for tool calls requiring user input
412
480
  */
@@ -432,6 +500,27 @@ declare interface SendMessageOptions {
432
500
  files?: File[];
433
501
  }
434
502
 
503
+ /**
504
+ * Where a completed form is sent.
505
+ * - `"https://..."` (a bare string) — shorthand for `{ via: "client", url }`: the browser
506
+ * POSTs the values to that URL.
507
+ * - `{ via: "client", url }` — same, written out.
508
+ * - `{ via: "client", handler }` — the browser runs your own submit logic.
509
+ * - `{ via: "backend", destination }` — the browser relays the values to the backend,
510
+ * which forwards them to the server-configured destination (URL + secret stay server-side).
511
+ * - `false` — collect only, no submit function.
512
+ */
513
+ declare type SubmitConfig<V = Record<string, unknown>> = string | {
514
+ via: "client";
515
+ url: string;
516
+ } | {
517
+ via: "client";
518
+ handler: (values: V) => Promise<unknown> | unknown;
519
+ } | {
520
+ via: "backend";
521
+ destination: string;
522
+ } | false;
523
+
435
524
  /**
436
525
  * Tool call data from SSE stream
437
526
  */
@@ -53,6 +53,13 @@ declare class AgoClient {
53
53
  * Reject a tool call
54
54
  */
55
55
  rejectToolCall(toolCallId: string): Promise<void>;
56
+ /**
57
+ * Fetch a backend-stored form collector definition by name (the single source
58
+ * of truth for the form's description, schema, and submit target). Used by
59
+ * `loadFormCollector` / the name-only form of `useFormCollector` so the schema
60
+ * lives in the backend instead of being hardcoded in client code.
61
+ */
62
+ getFormCollector(name: string): Promise<FormCollectorDefinition>;
56
63
  /**
57
64
  * Relay a completed form collector's values to a server-configured destination.
58
65
  *
@@ -399,6 +406,30 @@ export declare interface DevPanelOptions {
399
406
  */
400
407
  declare type DynamicContextProvider = () => ContextEntry | null | undefined;
401
408
 
409
+ /**
410
+ * The backend-stored shape returned by `GET /api/sdk/v1/forms/{name}` (see
411
+ * {@link AgoClient.getFormCollector}). Mirrors the persistable subset of
412
+ * {@link CreateFormCollectorOptions}: the `submit` here is never the client-only
413
+ * `handler` variant (a function can't be stored server-side).
414
+ */
415
+ declare interface FormCollectorDefinition<V = Record<string, unknown>> {
416
+ name: string;
417
+ description: string;
418
+ schema: FormCollectorSchema;
419
+ /** Server-stored submit target, if any. Absent means collect-only. */
420
+ submit?: SubmitConfig<V>;
421
+ }
422
+
423
+ /**
424
+ * Shape of a form's fields. Mirrors a client function's `parameters` (so the same
425
+ * 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.
426
+ */
427
+ declare interface FormCollectorSchema {
428
+ type: "object";
429
+ properties: Record<string, FormFieldSchema>;
430
+ required?: string[];
431
+ }
432
+
402
433
  declare interface FormField {
403
434
  type: "string" | "number" | "boolean" | "array";
404
435
  title?: string;
@@ -407,6 +438,43 @@ declare interface FormField {
407
438
  default?: unknown;
408
439
  }
409
440
 
441
+ /**
442
+ * A field's conditional-requiredness rule. The field becomes required exactly
443
+ * when the controlling `property` matches `value` against the answers collected
444
+ * so far:
445
+ * - a single `value`, no `op` — equality (compared as strings);
446
+ * - a single `value` with `op` — numeric comparison (both sides coerced to numbers);
447
+ * - an array `value`, no `op` — "one of": matches when the property equals any
448
+ * listed value.
449
+ *
450
+ * SDK-only — it is stripped from the schema before it reaches the LLM tool
451
+ */
452
+ declare interface FormFieldCondition {
453
+ /** The controlling field whose value the rule tests. */
454
+ property: string;
455
+ /** Comparison operator; omitted means equality. Ignored when `value` is an array. */
456
+ op?: ">=" | "<=" | ">" | "<";
457
+ /**
458
+ * The value(s) to test the controlling field against. A single value is an
459
+ * equality (or, with `op`, a numeric comparison); an array is an "is one of"
460
+ * membership test, e.g. `value: ["1", "2", "3"]`.
461
+ */
462
+ value: string | number | Array<string | number>;
463
+ }
464
+
465
+ /** A single field's schema: the wire-legal keys plus the SDK-only `requiredWhen`. */
466
+ declare interface FormFieldSchema {
467
+ type: string;
468
+ description?: string;
469
+ enum?: string[];
470
+ default?: unknown;
471
+ /**
472
+ * Makes the field required only while this condition holds. Drives the dynamic
473
+ * `missing` list; stripped before the LLM tool — see {@link toWireParameters}.
474
+ */
475
+ requiredWhen?: FormFieldCondition;
476
+ }
477
+
410
478
  /**
411
479
  * Form schema for tool calls requiring user input
412
480
  */
@@ -432,6 +500,27 @@ declare interface SendMessageOptions {
432
500
  files?: File[];
433
501
  }
434
502
 
503
+ /**
504
+ * Where a completed form is sent.
505
+ * - `"https://..."` (a bare string) — shorthand for `{ via: "client", url }`: the browser
506
+ * POSTs the values to that URL.
507
+ * - `{ via: "client", url }` — same, written out.
508
+ * - `{ via: "client", handler }` — the browser runs your own submit logic.
509
+ * - `{ via: "backend", destination }` — the browser relays the values to the backend,
510
+ * which forwards them to the server-configured destination (URL + secret stay server-side).
511
+ * - `false` — collect only, no submit function.
512
+ */
513
+ declare type SubmitConfig<V = Record<string, unknown>> = string | {
514
+ via: "client";
515
+ url: string;
516
+ } | {
517
+ via: "client";
518
+ handler: (values: V) => Promise<unknown> | unknown;
519
+ } | {
520
+ via: "backend";
521
+ destination: string;
522
+ } | false;
523
+
435
524
  /**
436
525
  * Tool call data from SSE stream
437
526
  */
package/dist/index.cjs CHANGED
@@ -1 +1 @@
1
- Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("./AgoClient-CPqPT5s6.cjs"),m=require("./createFormCollector-DaWZsBsI.cjs"),A=require("./createConversationSession-CGRO0bs2.cjs"),C=require("./createMockClient-zHQ0cjUH.cjs"),g=require("./functions-DsmzgHjC.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 v(e,o){return e.on("toolCall:received",o),()=>e.off("toolCall:received",o)}function M(e,o){return e.on("function:invoke",o),()=>e.off("function:invoke",o)}async function*k(e,o,l){const n=[];let r=null,a=!1;const c=s=>{n.push(s),r?.()},f=s=>c({type:"start",data:s}),t=s=>c({type:"chunk",data:s}),u=s=>{c({type:"complete",data:s}),a=!0,r?.()},d=s=>{c({type:"error",data:s}),a=!0,r?.()},p=s=>c({type:"toolCall",data:s});e.on("message:start",f),e.on("message:chunk",t),e.on("message:complete",u),e.on("message:error",d),e.on("toolCall:received",p),e.sendMessage(o,l).catch(()=>{a=!0,r?.()});try{for(;!a||n.length>0;)n.length>0?yield n.shift():(await new Promise(s=>{r=s}),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",p)}}function w(e){let o,l,n,r,a,c;if(typeof window<"u"&&window.AGO){const t=window.AGO;o=t.basepath,l=t.widgetId,n=t.agent||t.defaultAgent,r=t.permission,a=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"),n=n||t("ago-agent")||t("ago-agent-id"),r=r||t("ago-permission"),a=a||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,n=n||u.getAttribute("data-ago-agent")||u.getAttribute("data-ago-agent-id")||void 0,r=r||u.getAttribute("data-ago-permission")||void 0,a=a||u.getAttribute("data-ago-user-email")||void 0)}o=e?.baseUrl||o,l=e?.widgetId||l,n=e?.agent||e?.defaultAgentId||n,r=e?.permission||r,a=e?.userEmail||a,c=e?.userJwt||c;const f=e?.debug;return o?{baseUrl:o,widgetId:l,agent:n,permission:r,userEmail:a,userJwt:c,debug:f}:null}function F(e){const o=w(e);if(!o)throw new Error('createAgo(): could not detect AGO configuration. Set window.AGO, add <meta name="ago-base-url">, or pass { baseUrl } explicitly.');return new i.AgoClient(o)}function q(e,o){return{...e,handler:o}}exports.AgoApiError=i.AgoApiError;exports.AgoClient=i.AgoClient;exports.AgoError=i.AgoError;exports.AgoFunctionError=i.AgoFunctionError;exports.AgoNetworkError=i.AgoNetworkError;exports.AgoStreamError=i.AgoStreamError;exports.ClientContextRegistry=i.ClientContextRegistry;exports.EventEmitter=i.EventEmitter;exports.FunctionRegistry=i.FunctionRegistry;exports.SSEHandler=i.SSEHandler;exports.autoDetectConfig=w;exports.copyToClipboard=g.copyToClipboard;exports.createAgo=F;exports.createConversationSession=A.createConversationSession;exports.createFormCollector=m.createFormCollector;exports.createMessageStream=k;exports.createMockClient=C.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=i.isStreamNetworkError;exports.logger=i.logger;exports.onFunctionInvoke=M;exports.onMessage=E;exports.onMessageChunk=S;exports.onMessageError=b;exports.onMessageStart=y;exports.onToolCall=v;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.withHandler=q;
1
+ Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("./AgoClient-0x2Du_62.cjs"),f=require("./createFormCollector-Ca8wRrxc.cjs"),w=require("./createConversationSession-BLZvXMmM.cjs"),A=require("./createMockClient-zHQ0cjUH.cjs");require("./testing.cjs");const g=require("./functions-DsmzgHjC.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 v(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 n=[];let r=null,a=!1;const c=s=>{n.push(s),r?.()},m=s=>c({type:"start",data:s}),t=s=>c({type:"chunk",data:s}),u=s=>{c({type:"complete",data:s}),a=!0,r?.()},d=s=>{c({type:"error",data:s}),a=!0,r?.()},C=s=>c({type:"toolCall",data:s});e.on("message:start",m),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(()=>{a=!0,r?.()});try{for(;!a||n.length>0;)n.length>0?yield n.shift():(await new Promise(s=>{r=s}),r=null)}finally{e.off("message:start",m),e.off("message:chunk",t),e.off("message:complete",u),e.off("message:error",d),e.off("toolCall:received",C)}}function p(e){let o,l,n,r,a,c;if(typeof window<"u"&&window.AGO){const t=window.AGO;o=t.basepath,l=t.widgetId,n=t.agent||t.defaultAgent,r=t.permission,a=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"),n=n||t("ago-agent")||t("ago-agent-id"),r=r||t("ago-permission"),a=a||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,n=n||u.getAttribute("data-ago-agent")||u.getAttribute("data-ago-agent-id")||void 0,r=r||u.getAttribute("data-ago-permission")||void 0,a=a||u.getAttribute("data-ago-user-email")||void 0)}o=e?.baseUrl||o,l=e?.widgetId||l,n=e?.agent||e?.defaultAgentId||n,r=e?.permission||r,a=e?.userEmail||a,c=e?.userJwt||c;const m=e?.debug;return o?{baseUrl:o,widgetId:l,agent:n,permission:r,userEmail:a,userJwt:c,debug:m}:null}function k(e){const o=p(e);if(!o)throw new Error('createAgo(): could not detect AGO configuration. Set window.AGO, add <meta name="ago-base-url">, or pass { baseUrl } explicitly.');return new i.AgoClient(o)}function q(e,o){return{...e,handler:o}}exports.AgoApiError=i.AgoApiError;exports.AgoClient=i.AgoClient;exports.AgoError=i.AgoError;exports.AgoFunctionError=i.AgoFunctionError;exports.AgoNetworkError=i.AgoNetworkError;exports.AgoStreamError=i.AgoStreamError;exports.ClientContextRegistry=i.ClientContextRegistry;exports.EventEmitter=i.EventEmitter;exports.FunctionRegistry=i.FunctionRegistry;exports.SSEHandler=i.SSEHandler;exports.autoDetectConfig=p;exports.copyToClipboard=g.copyToClipboard;exports.createAgo=k;exports.createConversationSession=w.createConversationSession;exports.createFormCollector=f.createFormCollector;exports.createMessageStream=M;exports.createMockClient=A.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=i.isStreamNetworkError;exports.loadFormCollector=f.loadFormCollector;exports.logger=i.logger;exports.onFunctionInvoke=F;exports.onMessage=E;exports.onMessageChunk=S;exports.onMessageError=b;exports.onMessageStart=y;exports.onToolCall=v;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.withHandler=q;
package/dist/index.d.cts CHANGED
@@ -64,6 +64,13 @@ export declare class AgoClient {
64
64
  * Reject a tool call
65
65
  */
66
66
  rejectToolCall(toolCallId: string): Promise<void>;
67
+ /**
68
+ * Fetch a backend-stored form collector definition by name (the single source
69
+ * of truth for the form's description, schema, and submit target). Used by
70
+ * `loadFormCollector` / the name-only form of `useFormCollector` so the schema
71
+ * lives in the backend instead of being hardcoded in client code.
72
+ */
73
+ getFormCollector(name: string): Promise<FormCollectorDefinition>;
67
74
  /**
68
75
  * Relay a completed form collector's values to a server-configured destination.
69
76
  *
@@ -814,6 +821,22 @@ export declare interface FormCollector<V = Record<string, unknown>> {
814
821
  getValues: () => Partial<V>;
815
822
  setValues: (patch: Partial<V>) => void;
816
823
  reset: () => void;
824
+ /** Completeness status (`missing`/`complete`) derived from the current values + schema. */
825
+ getStatus: () => FormCollectorStatus;
826
+ }
827
+
828
+ /**
829
+ * The backend-stored shape returned by `GET /api/sdk/v1/forms/{name}` (see
830
+ * {@link AgoClient.getFormCollector}). Mirrors the persistable subset of
831
+ * {@link CreateFormCollectorOptions}: the `submit` here is never the client-only
832
+ * `handler` variant (a function can't be stored server-side).
833
+ */
834
+ export declare interface FormCollectorDefinition<V = Record<string, unknown>> {
835
+ name: string;
836
+ description: string;
837
+ schema: FormCollectorSchema;
838
+ /** Server-stored submit target, if any. Absent means collect-only. */
839
+ submit?: SubmitConfig<V>;
817
840
  }
818
841
 
819
842
  /**
@@ -988,6 +1011,30 @@ export declare const highlightElement: ClientFunctionDefinition;
988
1011
  */
989
1012
  export declare function isStreamNetworkError(error: Error): boolean;
990
1013
 
1014
+ /**
1015
+ * Async sibling of {@link createFormCollector} that pulls the form's definition
1016
+ * (description + schema + submit target) from the backend by name — the single
1017
+ * source of truth — instead of hardcoding it in client code. Any field passed in
1018
+ * `options` overrides the fetched one (e.g. a client-only `submit` handler or
1019
+ * `initialValues`).
1020
+ *
1021
+ * ```ts
1022
+ * const order = await loadFormCollector(client, { name: "order" });
1023
+ * order.install(client);
1024
+ * ```
1025
+ */
1026
+ export declare function loadFormCollector<V = Record<string, unknown>>(client: Pick<AgoClient, "getFormCollector">, options: LoadFormCollectorOptions<V>): Promise<FormCollector<V>>;
1027
+
1028
+ /**
1029
+ * Options for {@link loadFormCollector} / the name-only form of `useFormCollector`:
1030
+ * the `name` is required and the definition is fetched from the backend, while any
1031
+ * field here overrides the fetched one — notably a client-only `submit` handler,
1032
+ * which can't be stored server-side.
1033
+ */
1034
+ export declare interface LoadFormCollectorOptions<V = Record<string, unknown>> extends Partial<Omit<CreateFormCollectorOptions<V>, "name">> {
1035
+ name: string;
1036
+ }
1037
+
991
1038
  /**
992
1039
  * Debug logger for SDK
993
1040
  */
package/dist/index.d.ts CHANGED
@@ -64,6 +64,13 @@ export declare class AgoClient {
64
64
  * Reject a tool call
65
65
  */
66
66
  rejectToolCall(toolCallId: string): Promise<void>;
67
+ /**
68
+ * Fetch a backend-stored form collector definition by name (the single source
69
+ * of truth for the form's description, schema, and submit target). Used by
70
+ * `loadFormCollector` / the name-only form of `useFormCollector` so the schema
71
+ * lives in the backend instead of being hardcoded in client code.
72
+ */
73
+ getFormCollector(name: string): Promise<FormCollectorDefinition>;
67
74
  /**
68
75
  * Relay a completed form collector's values to a server-configured destination.
69
76
  *
@@ -814,6 +821,22 @@ export declare interface FormCollector<V = Record<string, unknown>> {
814
821
  getValues: () => Partial<V>;
815
822
  setValues: (patch: Partial<V>) => void;
816
823
  reset: () => void;
824
+ /** Completeness status (`missing`/`complete`) derived from the current values + schema. */
825
+ getStatus: () => FormCollectorStatus;
826
+ }
827
+
828
+ /**
829
+ * The backend-stored shape returned by `GET /api/sdk/v1/forms/{name}` (see
830
+ * {@link AgoClient.getFormCollector}). Mirrors the persistable subset of
831
+ * {@link CreateFormCollectorOptions}: the `submit` here is never the client-only
832
+ * `handler` variant (a function can't be stored server-side).
833
+ */
834
+ export declare interface FormCollectorDefinition<V = Record<string, unknown>> {
835
+ name: string;
836
+ description: string;
837
+ schema: FormCollectorSchema;
838
+ /** Server-stored submit target, if any. Absent means collect-only. */
839
+ submit?: SubmitConfig<V>;
817
840
  }
818
841
 
819
842
  /**
@@ -988,6 +1011,30 @@ export declare const highlightElement: ClientFunctionDefinition;
988
1011
  */
989
1012
  export declare function isStreamNetworkError(error: Error): boolean;
990
1013
 
1014
+ /**
1015
+ * Async sibling of {@link createFormCollector} that pulls the form's definition
1016
+ * (description + schema + submit target) from the backend by name — the single
1017
+ * source of truth — instead of hardcoding it in client code. Any field passed in
1018
+ * `options` overrides the fetched one (e.g. a client-only `submit` handler or
1019
+ * `initialValues`).
1020
+ *
1021
+ * ```ts
1022
+ * const order = await loadFormCollector(client, { name: "order" });
1023
+ * order.install(client);
1024
+ * ```
1025
+ */
1026
+ export declare function loadFormCollector<V = Record<string, unknown>>(client: Pick<AgoClient, "getFormCollector">, options: LoadFormCollectorOptions<V>): Promise<FormCollector<V>>;
1027
+
1028
+ /**
1029
+ * Options for {@link loadFormCollector} / the name-only form of `useFormCollector`:
1030
+ * the `name` is required and the definition is fetched from the backend, while any
1031
+ * field here overrides the fetched one — notably a client-only `submit` handler,
1032
+ * which can't be stored server-side.
1033
+ */
1034
+ export declare interface LoadFormCollectorOptions<V = Record<string, unknown>> extends Partial<Omit<CreateFormCollectorOptions<V>, "name">> {
1035
+ name: string;
1036
+ }
1037
+
991
1038
  /**
992
1039
  * Debug logger for SDK
993
1040
  */
package/dist/index.js CHANGED
@@ -1,30 +1,31 @@
1
- import { a as w, c as h, d as A, f as y, i as C, l as E, n as S, o as b, r as v, s as k, t as d, u as M } from "./AgoClient-BrYhSO5M.js";
2
- import { n as T, r as I, t as U } from "./createFormCollector-CPS2phYq.js";
3
- import { t as O } from "./createConversationSession-Dmqd80DX.js";
4
- import { t as x } from "./createMockClient-DwdxNwEn.js";
5
- import { a as N, c as D, d as H, f as J, i as R, l as j, m as B, o as P, p as $, r as z, s as K, t as Q, u as V } from "./functions-C1-5vadY.js";
6
- function W(e) {
1
+ import { a as w, c as h, d as A, f as y, i as C, l as E, n as S, o as b, r as v, s as k, t as d, u as F } from "./AgoClient-CZYNL25R.js";
2
+ import { i as T, n as I, r as U, t as G } from "./createFormCollector-Bk0DRhUf.js";
3
+ import { t as q } from "./createConversationSession-Bmqj2rSS.js";
4
+ import { t as L } from "./createMockClient-DwdxNwEn.js";
5
+ import "./testing.js";
6
+ import { a as H, c as J, d as R, f as j, i as B, l as P, m as $, o as z, p as K, r as Q, s as V, t as W, u as X } from "./functions-C1-5vadY.js";
7
+ function Y(e) {
7
8
  return e;
8
9
  }
9
- function X(e, t) {
10
- return e.on("message:complete", t), () => e.off("message:complete", t);
10
+ function Z(e, o) {
11
+ return e.on("message:complete", o), () => e.off("message:complete", o);
11
12
  }
12
- function Y(e, t) {
13
- return e.on("message:chunk", t), () => e.off("message:chunk", t);
13
+ function _(e, o) {
14
+ return e.on("message:chunk", o), () => e.off("message:chunk", o);
14
15
  }
15
- function Z(e, t) {
16
- return e.on("message:start", t), () => e.off("message:start", t);
16
+ function ee(e, o) {
17
+ return e.on("message:start", o), () => e.off("message:start", o);
17
18
  }
18
- function _(e, t) {
19
- return e.on("message:error", t), () => e.off("message:error", t);
19
+ function oe(e, o) {
20
+ return e.on("message:error", o), () => e.off("message:error", o);
20
21
  }
21
- function ee(e, t) {
22
- return e.on("toolCall:received", t), () => e.off("toolCall:received", t);
22
+ function te(e, o) {
23
+ return e.on("toolCall:received", o), () => e.off("toolCall:received", o);
23
24
  }
24
- function te(e, t) {
25
- return e.on("function:invoke", t), () => e.off("function:invoke", t);
25
+ function re(e, o) {
26
+ return e.on("function:invoke", o), () => e.off("function:invoke", o);
26
27
  }
27
- async function* oe(e, t, g) {
28
+ async function* ae(e, o, g) {
28
29
  const a = [];
29
30
  let r = null, n = !1;
30
31
  const u = (s) => {
@@ -32,7 +33,7 @@ async function* oe(e, t, g) {
32
33
  }, f = (s) => u({
33
34
  type: "start",
34
35
  data: s
35
- }), o = (s) => u({
36
+ }), t = (s) => u({
36
37
  type: "chunk",
37
38
  data: s
38
39
  }), i = (s) => {
@@ -49,7 +50,7 @@ async function* oe(e, t, g) {
49
50
  type: "toolCall",
50
51
  data: s
51
52
  });
52
- e.on("message:start", f), e.on("message:chunk", o), e.on("message:complete", i), e.on("message:error", m), e.on("toolCall:received", l), e.sendMessage(t, g).catch(() => {
53
+ e.on("message:start", f), e.on("message:chunk", t), e.on("message:complete", i), e.on("message:error", m), e.on("toolCall:received", l), e.sendMessage(o, g).catch(() => {
53
54
  n = !0, r?.();
54
55
  });
55
56
  try {
@@ -57,28 +58,28 @@ async function* oe(e, t, g) {
57
58
  r = s;
58
59
  }), r = null);
59
60
  } finally {
60
- e.off("message:start", f), e.off("message:chunk", o), e.off("message:complete", i), e.off("message:error", m), e.off("toolCall:received", l);
61
+ e.off("message:start", f), e.off("message:chunk", t), e.off("message:complete", i), e.off("message:error", m), e.off("toolCall:received", l);
61
62
  }
62
63
  }
63
64
  function c(e) {
64
- let t, g, a, r, n, u;
65
+ let o, g, a, r, n, u;
65
66
  if (typeof window < "u" && window.AGO) {
66
- const o = window.AGO;
67
- t = o.basepath, g = o.widgetId, a = o.agent || o.defaultAgent, r = o.permission, n = o.email, u = o.jwt;
67
+ const t = window.AGO;
68
+ o = t.basepath, g = t.widgetId, a = t.agent || t.defaultAgent, r = t.permission, n = t.email, u = t.jwt;
68
69
  }
69
70
  if (typeof document < "u") {
70
- const o = (i) => document.querySelector(`meta[name="${i}"]`)?.getAttribute("content") || void 0;
71
- t = t || o("ago-base-url"), g = g || o("ago-widget-id"), a = a || o("ago-agent") || o("ago-agent-id"), r = r || o("ago-permission"), n = n || o("ago-user-email");
71
+ const t = (i) => document.querySelector(`meta[name="${i}"]`)?.getAttribute("content") || void 0;
72
+ o = o || t("ago-base-url"), g = g || t("ago-widget-id"), a = a || t("ago-agent") || t("ago-agent-id"), r = r || t("ago-permission"), n = n || t("ago-user-email");
72
73
  }
73
74
  if (typeof document < "u") {
74
- const o = [document.body, ...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);
75
- for (const i of o)
76
- i && (t = t || i.getAttribute("data-ago-base-url") || void 0, g = g || i.getAttribute("data-ago-widget-id") || void 0, a = a || i.getAttribute("data-ago-agent") || i.getAttribute("data-ago-agent-id") || void 0, r = r || i.getAttribute("data-ago-permission") || void 0, n = n || i.getAttribute("data-ago-user-email") || void 0);
75
+ const t = [document.body, ...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);
76
+ for (const i of t)
77
+ i && (o = o || i.getAttribute("data-ago-base-url") || void 0, g = g || i.getAttribute("data-ago-widget-id") || void 0, a = a || i.getAttribute("data-ago-agent") || i.getAttribute("data-ago-agent-id") || void 0, r = r || i.getAttribute("data-ago-permission") || void 0, n = n || i.getAttribute("data-ago-user-email") || void 0);
77
78
  }
78
- t = e?.baseUrl || t, g = e?.widgetId || g, a = e?.agent || e?.defaultAgentId || a, r = e?.permission || r, n = e?.userEmail || n, u = e?.userJwt || u;
79
+ o = e?.baseUrl || o, g = e?.widgetId || g, a = e?.agent || e?.defaultAgentId || a, r = e?.permission || r, n = e?.userEmail || n, u = e?.userJwt || u;
79
80
  const f = e?.debug;
80
- return t ? {
81
- baseUrl: t,
81
+ return o ? {
82
+ baseUrl: o,
82
83
  widgetId: g,
83
84
  agent: a,
84
85
  permission: r,
@@ -87,22 +88,22 @@ function c(e) {
87
88
  debug: f
88
89
  } : null;
89
90
  }
90
- function re(e) {
91
- const t = c(e);
92
- if (!t) throw new Error('createAgo(): could not detect AGO configuration. Set window.AGO, add <meta name="ago-base-url">, or pass { baseUrl } explicitly.');
93
- return new d(t);
91
+ function ne(e) {
92
+ const o = c(e);
93
+ if (!o) throw new Error('createAgo(): could not detect AGO configuration. Set window.AGO, add <meta name="ago-base-url">, or pass { baseUrl } explicitly.');
94
+ return new d(o);
94
95
  }
95
- function ae(e, t) {
96
+ function se(e, o) {
96
97
  return {
97
98
  ...e,
98
- handler: t
99
+ handler: o
99
100
  };
100
101
  }
101
102
  export {
102
103
  h as AgoApiError,
103
104
  d as AgoClient,
104
105
  E as AgoError,
105
- M as AgoFunctionError,
106
+ F as AgoFunctionError,
106
107
  A as AgoNetworkError,
107
108
  y as AgoStreamError,
108
109
  w as ClientContextRegistry,
@@ -110,34 +111,35 @@ export {
110
111
  b as FunctionRegistry,
111
112
  v as SSEHandler,
112
113
  c as autoDetectConfig,
113
- Q as copyToClipboard,
114
- re as createAgo,
115
- O as createConversationSession,
116
- U as createFormCollector,
117
- oe as createMessageStream,
118
- x as createMockClient,
119
- I as createStore,
120
- W as defineFunction,
121
- T as deriveFormStatus,
122
- z as getLocalStorage,
123
- R as getUserLocation,
124
- N as highlightElement,
114
+ W as copyToClipboard,
115
+ ne as createAgo,
116
+ q as createConversationSession,
117
+ G as createFormCollector,
118
+ ae as createMessageStream,
119
+ L as createMockClient,
120
+ T as createStore,
121
+ Y as defineFunction,
122
+ I as deriveFormStatus,
123
+ Q as getLocalStorage,
124
+ B as getUserLocation,
125
+ H as highlightElement,
125
126
  C as isStreamNetworkError,
127
+ U as loadFormCollector,
126
128
  k as logger,
127
- te as onFunctionInvoke,
128
- X as onMessage,
129
- Y as onMessageChunk,
130
- _ as onMessageError,
131
- Z as onMessageStart,
132
- ee as onToolCall,
133
- P as openUrl,
134
- K as scrollToElement,
135
- D as setLocalStorage,
136
- j as setTheme,
137
- V as showConfirmDialog,
138
- H as showNotification,
139
- J as showToast,
140
- $ as submitForm,
141
- B as trackEvent,
142
- ae as withHandler
129
+ re as onFunctionInvoke,
130
+ Z as onMessage,
131
+ _ as onMessageChunk,
132
+ oe as onMessageError,
133
+ ee as onMessageStart,
134
+ te as onToolCall,
135
+ z as openUrl,
136
+ V as scrollToElement,
137
+ J as setLocalStorage,
138
+ P as setTheme,
139
+ X as showConfirmDialog,
140
+ R as showNotification,
141
+ j as showToast,
142
+ K as submitForm,
143
+ $ as trackEvent,
144
+ se as withHandler
143
145
  };