@useago/sdk 1.0.0 → 1.0.1

package/dist/widget.d.cts

@@ -53,6 +53,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.
      *
@@ -345,6 +352,13 @@ export declare interface ChatWidgetHandle {
     element: HTMLElement;
     /** Programmatically send a message (same path as the input). */
     sendMessage: (content: string, files?: File[]) => Promise<void>;
+    /**
+     * Open / close / toggle the side panel. Present only for
+     * `placement: "left" | "right"` (an inline panel is always visible).
+     */
+    open?: () => void;
+    close?: () => void;
+    toggle?: () => void;
     /**
      * The conversation-persistence session, present only when `persistConversation`
      * is set — exposes the stable `widgetId` and `session.clear()` to start a new thread.
@@ -520,6 +534,20 @@ export declare interface CreateFormCollectorOptions<V = Record<string, unknown>>
  */
 declare type DynamicContextProvider = () => ContextEntry | null | undefined;
 
+/**
+ * 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).
+ */
+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>;
+}
+
 /**
  * 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.
@@ -584,6 +612,16 @@ declare interface FormSchema {
     required?: string[];
 }
 
+/**
+ * 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.
+ */
+declare interface LoadFormCollectorOptions<V = Record<string, unknown>> extends Partial<Omit<CreateFormCollectorOptions<V>, "name">> {
+    name: string;
+}
+
 declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED";
 
 /**
@@ -646,9 +684,37 @@ export declare interface MountChatWidgetOptions {
     placeholder?: string;
     /** Enable file attachments. */
     allowFiles?: boolean;
-    /** Widget height (number → px). */
+    /** Widget height (number → px). Ignored when `placement` is `"left"`/`"right"`
+     * (a side panel is always full-height). */
     height?: string | number;
-    /** URL of a logo shown in the header. */
+    /**
+     * Where the panel renders. `"inline"` (default) mounts it directly into the
+     * target element, filling it. `"left"` / `"right"` instead pin a **fixed,
+     * full-height side panel** to that edge of the viewport that slides open and
+     * closed; the target is only used as the DOM parent (pass `document.body` for
+     * a true page overlay). In side mode `height` is ignored and the width comes
+     * from {@link MountChatWidgetOptions.width}.
+     */
+    placement?: "inline" | "left" | "right";
+    /**
+     * Width of the side panel for `placement: "left" | "right"` (number → px).
+     * Capped at the viewport width so it never overflows on mobile. Ignored when
+     * `placement` is `"inline"`. Defaults to `400`.
+     */
+    width?: string | number;
+    /**
+     * For side placements, render the built-in floating launcher button that opens
+     * the panel (plus a close "×" in the header). Set `false` to drive open/close
+     * yourself via the handle's `open()`/`close()`/`toggle()`. Ignored when
+     * `placement` is `"inline"`. Defaults to `true`.
+     */
+    launcher?: boolean;
+    /**
+     * For side placements, whether the panel starts open. Ignored when `placement`
+     * is `"inline"` (an inline panel is always visible). Defaults to `false`.
+     */
+    defaultOpen?: boolean;
+    /** URL of a logo shown in the header (and on the launcher button, if shown). */
     logoUrl?: string;
     /** Show the agent name above assistant messages. Defaults to `false`. */
     showAgentName?: boolean;
@@ -665,10 +731,13 @@ export declare interface MountChatWidgetOptions {
     loadThreads?: boolean;
     /**
      * Conversational forms the agent can fill and submit during the chat. Each
-     * config is installed as a {@link createFormCollector} for the lifetime of the
+     * entry is installed as a {@link createFormCollector} for the lifetime of the
      * widget (removed on `destroy()`).
+     *
+     * 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

package/dist/widget.d.ts

@@ -53,6 +53,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.
      *
@@ -345,6 +352,13 @@ export declare interface ChatWidgetHandle {
     element: HTMLElement;
     /** Programmatically send a message (same path as the input). */
     sendMessage: (content: string, files?: File[]) => Promise<void>;
+    /**
+     * Open / close / toggle the side panel. Present only for
+     * `placement: "left" | "right"` (an inline panel is always visible).
+     */
+    open?: () => void;
+    close?: () => void;
+    toggle?: () => void;
     /**
      * The conversation-persistence session, present only when `persistConversation`
      * is set — exposes the stable `widgetId` and `session.clear()` to start a new thread.
@@ -520,6 +534,20 @@ export declare interface CreateFormCollectorOptions<V = Record<string, unknown>>
  */
 declare type DynamicContextProvider = () => ContextEntry | null | undefined;
 
+/**
+ * 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).
+ */
+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>;
+}
+
 /**
  * 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.
@@ -584,6 +612,16 @@ declare interface FormSchema {
     required?: string[];
 }
 
+/**
+ * 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.
+ */
+declare interface LoadFormCollectorOptions<V = Record<string, unknown>> extends Partial<Omit<CreateFormCollectorOptions<V>, "name">> {
+    name: string;
+}
+
 declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED";
 
 /**
@@ -646,9 +684,37 @@ export declare interface MountChatWidgetOptions {
     placeholder?: string;
     /** Enable file attachments. */
     allowFiles?: boolean;
-    /** Widget height (number → px). */
+    /** Widget height (number → px). Ignored when `placement` is `"left"`/`"right"`
+     * (a side panel is always full-height). */
     height?: string | number;
-    /** URL of a logo shown in the header. */
+    /**
+     * Where the panel renders. `"inline"` (default) mounts it directly into the
+     * target element, filling it. `"left"` / `"right"` instead pin a **fixed,
+     * full-height side panel** to that edge of the viewport that slides open and
+     * closed; the target is only used as the DOM parent (pass `document.body` for
+     * a true page overlay). In side mode `height` is ignored and the width comes
+     * from {@link MountChatWidgetOptions.width}.
+     */
+    placement?: "inline" | "left" | "right";
+    /**
+     * Width of the side panel for `placement: "left" | "right"` (number → px).
+     * Capped at the viewport width so it never overflows on mobile. Ignored when
+     * `placement` is `"inline"`. Defaults to `400`.
+     */
+    width?: string | number;
+    /**
+     * For side placements, render the built-in floating launcher button that opens
+     * the panel (plus a close "×" in the header). Set `false` to drive open/close
+     * yourself via the handle's `open()`/`close()`/`toggle()`. Ignored when
+     * `placement` is `"inline"`. Defaults to `true`.
+     */
+    launcher?: boolean;
+    /**
+     * For side placements, whether the panel starts open. Ignored when `placement`
+     * is `"inline"` (an inline panel is always visible). Defaults to `false`.
+     */
+    defaultOpen?: boolean;
+    /** URL of a logo shown in the header (and on the launcher button, if shown). */
     logoUrl?: string;
     /** Show the agent name above assistant messages. Defaults to `false`. */
     showAgentName?: boolean;
@@ -665,10 +731,13 @@ export declare interface MountChatWidgetOptions {
     loadThreads?: boolean;
     /**
      * Conversational forms the agent can fill and submit during the chat. Each
-     * config is installed as a {@link createFormCollector} for the lifetime of the
+     * entry is installed as a {@link createFormCollector} for the lifetime of the
      * widget (removed on `destroy()`).
+     *
+     * 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