@useago/sdk 0.4.7 → 1.0.1

package/dist/react.d.cts

@@ -55,6 +55,13 @@ declare class AgoClient {
      * Reject a tool call
      */
     rejectToolCall(toolCallId: string): Promise<void>;
+    /**
+     * Fetch a backend-stored form collector definition by name (the single source
+     * of truth for the form's description, schema, and submit target). Used by
+     * `loadFormCollector` / the name-only form of `useFormCollector` so the schema
+     * lives in the backend instead of being hardcoded in client code.
+     */
+    getFormCollector(name: string): Promise<FormCollectorDefinition>;
     /**
      * Relay a completed form collector's values to a server-configured destination.
      *
@@ -395,10 +402,13 @@ export declare interface ChatWidgetProps {
     showAgentName?: boolean;
     /**
      * Conversational forms the agent can fill and submit during the chat. Each
-     * config is installed as a {@link createFormCollector} (its `update_<name>` /
+     * entry is installed as a {@link createFormCollector} (its `update_<name>` /
      * `submit_<name>` functions + dynamic context) for the lifetime of the widget.
+     *
+     * Pass a full config (with `schema`) to define it inline, or just `{ name }` to
+     * fetch the definition from the backend ({@link loadFormCollector}).
      */
-    forms?: CreateFormCollectorOptions[];
+    forms?: Array<CreateFormCollectorOptions | LoadFormCollectorOptions>;
     /**
      * How clicking a suggested follow-up reply behaves. Defaults to sending the
      * reply as a new user message. Pass a handler to override, or `false` to
@@ -592,6 +602,22 @@ export declare interface FormCollector<V = Record<string, unknown>> {
     getValues: () => Partial<V>;
     setValues: (patch: Partial<V>) => void;
     reset: () => void;
+    /** Completeness status (`missing`/`complete`) derived from the current values + schema. */
+    getStatus: () => FormCollectorStatus;
+}
+
+/**
+ * The backend-stored shape returned by `GET /api/sdk/v1/forms/{name}` (see
+ * {@link AgoClient.getFormCollector}). Mirrors the persistable subset of
+ * {@link CreateFormCollectorOptions}: the `submit` here is never the client-only
+ * `handler` variant (a function can't be stored server-side).
+ */
+export declare interface FormCollectorDefinition<V = Record<string, unknown>> {
+    name: string;
+    description: string;
+    schema: FormCollectorSchema;
+    /** Server-stored submit target, if any. Absent means collect-only. */
+    submit?: SubmitConfig<V>;
 }
 
 /**
@@ -682,6 +708,30 @@ export declare interface FormSubmitResult {
     error?: string;
 }
 
+/**
+ * Async sibling of {@link createFormCollector} that pulls the form's definition
+ * (description + schema + submit target) from the backend by name — the single
+ * source of truth — instead of hardcoding it in client code. Any field passed in
+ * `options` overrides the fetched one (e.g. a client-only `submit` handler or
+ * `initialValues`).
+ *
+ * ```ts
+ * const order = await loadFormCollector(client, { name: "order" });
+ * order.install(client);
+ * ```
+ */
+export declare function loadFormCollector<V = Record<string, unknown>>(client: Pick<AgoClient, "getFormCollector">, options: LoadFormCollectorOptions<V>): Promise<FormCollector<V>>;
+
+/**
+ * Options for {@link loadFormCollector} / the name-only form of `useFormCollector`:
+ * the `name` is required and the definition is fetched from the backend, while any
+ * field here overrides the fetched one — notably a client-only `submit` handler,
+ * which can't be stored server-side.
+ */
+export declare interface LoadFormCollectorOptions<V = Record<string, unknown>> extends Partial<Omit<CreateFormCollectorOptions<V>, "name">> {
+    name: string;
+}
+
 /**
  * Renders markdown content with GitHub-flavored markdown support
  * (tables, task lists, strikethrough, autolinks) and inline-styled
@@ -1039,32 +1089,26 @@ export declare interface UseConversationResult {
  * functions + dynamic context on mount, removes them on unmount, and returns the
  * live store state.
  *
- * The collector is recreated only when `name`, the schema, or the submit target
- * changes. Keep the schema and submit object stable (declare them outside render
- * or memoize them) so an inline `handler` isn't captured stale.
+ * Two modes, by whether you pass a `schema`:
+ *
+ * - **Inline** — pass `{ name, description, schema, submit? }` and the collector is
+ *   built synchronously (recreated only when `name`, the schema, or the submit
+ *   target changes; keep them stable). `loading` is always `false`.
+ * - **Backend** — pass `{ name }` (no `schema`) and the definition is fetched from
+ *   the backend ({@link loadFormCollector}) so the schema lives server-side, not in
+ *   client code. `loading` is `true` until it resolves; any field you do pass
+ *   overrides the fetched one (e.g. a client-only `submit` handler).
  *
  * ```tsx
- * const order = useFormCollector({
- *   name: "order",
- *   description: "The order the user wants to place",
- *   schema: {
- *     type: "object",
- *     properties: { product: { type: "string" }, quantity: { type: "number" } },
- *     required: ["product", "quantity"],
- *   },
- *   submit: { via: "backend", destination: "order_webhook" },
- * });
+ * // Backend-defined form — schema lives in the backend:
+ * const order = useFormCollector({ name: "order" });
  *
- * return (
- *   <div>
- *     {order.state.missing.length > 0
- *       ? `Still need: ${order.state.missing.join(", ")}`
- *       : "Ready to submit"}
- *   </div>
- * );
+ * return order.loading
+ *   ? <p>Loading…</p>
+ *   : <p>{order.state.missing.length ? `Still need: ${order.state.missing.join(", ")}` : "Ready"}</p>;
  * ```
  */
-export declare function useFormCollector<V = Record<string, unknown>>(options: CreateFormCollectorOptions<V>): UseFormCollectorResult<V>;
+export declare function useFormCollector<V = Record<string, unknown>>(options: CreateFormCollectorOptions<V> | LoadFormCollectorOptions<V>): UseFormCollectorResult<V>;
 
 export declare interface UseFormCollectorResult<V = Record<string, unknown>> extends FormCollector<V> {
     /**
@@ -1072,6 +1116,13 @@ export declare interface UseFormCollectorResult<V = Record<string, unknown>> ext
      * status (`missing`, `complete`) derived on read — re-renders on every change.
      */
     state: FormCollectorState<V> & FormCollectorStatus;
+    /**
+     * True while the backend definition is being fetched (name-only usage). Always
+     * `false` when an inline `schema` is provided.
+     */
+    loading: boolean;
+    /** Set if fetching the backend definition failed. */
+    error: Error | null;
 }
 
 /**

package/dist/react.d.ts

@@ -55,6 +55,13 @@ declare class AgoClient {
      * Reject a tool call
      */
     rejectToolCall(toolCallId: string): Promise<void>;
+    /**
+     * Fetch a backend-stored form collector definition by name (the single source
+     * of truth for the form's description, schema, and submit target). Used by
+     * `loadFormCollector` / the name-only form of `useFormCollector` so the schema
+     * lives in the backend instead of being hardcoded in client code.
+     */
+    getFormCollector(name: string): Promise<FormCollectorDefinition>;
     /**
      * Relay a completed form collector's values to a server-configured destination.
      *
@@ -395,10 +402,13 @@ export declare interface ChatWidgetProps {
     showAgentName?: boolean;
     /**
      * Conversational forms the agent can fill and submit during the chat. Each
-     * config is installed as a {@link createFormCollector} (its `update_<name>` /
+     * entry is installed as a {@link createFormCollector} (its `update_<name>` /
      * `submit_<name>` functions + dynamic context) for the lifetime of the widget.
+     *
+     * Pass a full config (with `schema`) to define it inline, or just `{ name }` to
+     * fetch the definition from the backend ({@link loadFormCollector}).
      */
-    forms?: CreateFormCollectorOptions[];
+    forms?: Array<CreateFormCollectorOptions | LoadFormCollectorOptions>;
     /**
      * How clicking a suggested follow-up reply behaves. Defaults to sending the
      * reply as a new user message. Pass a handler to override, or `false` to
@@ -592,6 +602,22 @@ export declare interface FormCollector<V = Record<string, unknown>> {
     getValues: () => Partial<V>;
     setValues: (patch: Partial<V>) => void;
     reset: () => void;
+    /** Completeness status (`missing`/`complete`) derived from the current values + schema. */
+    getStatus: () => FormCollectorStatus;
+}
+
+/**
+ * The backend-stored shape returned by `GET /api/sdk/v1/forms/{name}` (see
+ * {@link AgoClient.getFormCollector}). Mirrors the persistable subset of
+ * {@link CreateFormCollectorOptions}: the `submit` here is never the client-only
+ * `handler` variant (a function can't be stored server-side).
+ */
+export declare interface FormCollectorDefinition<V = Record<string, unknown>> {
+    name: string;
+    description: string;
+    schema: FormCollectorSchema;
+    /** Server-stored submit target, if any. Absent means collect-only. */
+    submit?: SubmitConfig<V>;
 }
 
 /**
@@ -682,6 +708,30 @@ export declare interface FormSubmitResult {
     error?: string;
 }
 
+/**
+ * Async sibling of {@link createFormCollector} that pulls the form's definition
+ * (description + schema + submit target) from the backend by name — the single
+ * source of truth — instead of hardcoding it in client code. Any field passed in
+ * `options` overrides the fetched one (e.g. a client-only `submit` handler or
+ * `initialValues`).
+ *
+ * ```ts
+ * const order = await loadFormCollector(client, { name: "order" });
+ * order.install(client);
+ * ```
+ */
+export declare function loadFormCollector<V = Record<string, unknown>>(client: Pick<AgoClient, "getFormCollector">, options: LoadFormCollectorOptions<V>): Promise<FormCollector<V>>;
+
+/**
+ * Options for {@link loadFormCollector} / the name-only form of `useFormCollector`:
+ * the `name` is required and the definition is fetched from the backend, while any
+ * field here overrides the fetched one — notably a client-only `submit` handler,
+ * which can't be stored server-side.
+ */
+export declare interface LoadFormCollectorOptions<V = Record<string, unknown>> extends Partial<Omit<CreateFormCollectorOptions<V>, "name">> {
+    name: string;
+}
+
 /**
  * Renders markdown content with GitHub-flavored markdown support
  * (tables, task lists, strikethrough, autolinks) and inline-styled
@@ -1039,32 +1089,26 @@ export declare interface UseConversationResult {
  * functions + dynamic context on mount, removes them on unmount, and returns the
  * live store state.
  *
- * The collector is recreated only when `name`, the schema, or the submit target
- * changes. Keep the schema and submit object stable (declare them outside render
- * or memoize them) so an inline `handler` isn't captured stale.
+ * Two modes, by whether you pass a `schema`:
+ *
+ * - **Inline** — pass `{ name, description, schema, submit? }` and the collector is
+ *   built synchronously (recreated only when `name`, the schema, or the submit
+ *   target changes; keep them stable). `loading` is always `false`.
+ * - **Backend** — pass `{ name }` (no `schema`) and the definition is fetched from
+ *   the backend ({@link loadFormCollector}) so the schema lives server-side, not in
+ *   client code. `loading` is `true` until it resolves; any field you do pass
+ *   overrides the fetched one (e.g. a client-only `submit` handler).
  *
  * ```tsx
- * const order = useFormCollector({
- *   name: "order",
- *   description: "The order the user wants to place",
- *   schema: {
- *     type: "object",
- *     properties: { product: { type: "string" }, quantity: { type: "number" } },
- *     required: ["product", "quantity"],
- *   },
- *   submit: { via: "backend", destination: "order_webhook" },
- * });
+ * // Backend-defined form — schema lives in the backend:
+ * const order = useFormCollector({ name: "order" });
  *
- * return (
- *   <div>
- *     {order.state.missing.length > 0
- *       ? `Still need: ${order.state.missing.join(", ")}`
- *       : "Ready to submit"}
- *   </div>
- * );
+ * return order.loading
+ *   ? <p>Loading…</p>
+ *   : <p>{order.state.missing.length ? `Still need: ${order.state.missing.join(", ")}` : "Ready"}</p>;
  * ```
  */
-export declare function useFormCollector<V = Record<string, unknown>>(options: CreateFormCollectorOptions<V>): UseFormCollectorResult<V>;
+export declare function useFormCollector<V = Record<string, unknown>>(options: CreateFormCollectorOptions<V> | LoadFormCollectorOptions<V>): UseFormCollectorResult<V>;
 
 export declare interface UseFormCollectorResult<V = Record<string, unknown>> extends FormCollector<V> {
     /**
@@ -1072,6 +1116,13 @@ export declare interface UseFormCollectorResult<V = Record<string, unknown>> ext
      * status (`missing`, `complete`) derived on read — re-renders on every change.
      */
     state: FormCollectorState<V> & FormCollectorStatus;
+    /**
+     * True while the backend definition is being fetched (name-only usage). Always
+     * `false` when an inline `schema` is provided.
+     */
+    loading: boolean;
+    /** Set if fetching the backend definition failed. */
+    error: Error | null;
 }
 
 /**