@useago/sdk 1.0.7 → 1.0.9

package/dist/widget.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;
     };
@@ -611,7 +633,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";
@@ -628,17 +650,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. */
@@ -659,7 +696,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;
 }
@@ -779,6 +817,16 @@ export declare interface MountChatWidgetOptions {
     logoUrl?: string;
     /** Show the agent name above assistant messages. Defaults to `false`. */
     showAgentName?: boolean;
+    /** Render assistant messages inside a filled bubble (themed via `agentBubbleBg`). Defaults to `false`. */
+    agentBubble?: boolean;
+    /**
+     * Show the header bar (title, logo, and the side-panel close "×"). Set `false`
+     * to drop it, e.g. when the host page already frames the widget. Defaults to
+     * `true`. Note: with the built-in launcher in side placement, the close "×"
+     * lives in the header, so hiding it leaves the launcher (and `widget.close()`)
+     * as the way to dismiss the panel.
+     */
+    showHeader?: boolean;
     /**
      * Theme overrides so the panel blends into the host page.
      */
@@ -822,6 +870,25 @@ export declare interface MountChatWidgetOptions {
         id: string;
         content: string;
     }) => void;
+    /**
+     * Called when a form collector submits successfully. `result` is the raw submit
+     * response (the third-party API's answer); `values` are the submitted fields.
+     * Forwards the client's `form:submitted` event.
+     */
+    onFormSubmitted?: (data: {
+        name: string;
+        values: Record<string, unknown>;
+        result: unknown;
+    }) => void;
+    /**
+     * Called when a form collector submit fails at the network/server level.
+     * Forwards the client's `form:error` event. No notice is shown in the chat.
+     */
+    onFormError?: (data: {
+        name: string;
+        values: Record<string, unknown>;
+        error: string;
+    }) => void;
 }
 
 /**
@@ -979,6 +1046,8 @@ export declare interface WidgetTheme {
     border?: string;
     /** Secondary accent: source badges and suggested-reply hover outline. (`--ago-accent-color`) */
     accent?: string;
+    /** Background of assistant message bubbles when `agentBubble` is on. Defaults to a light gray. (`--ago-agent-bubble-background`) */
+    agentBubbleBg?: string;
 }
 
 export { }

package/dist/widget.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;
     };
@@ -611,7 +633,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";
@@ -628,17 +650,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. */
@@ -659,7 +696,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;
 }
@@ -779,6 +817,16 @@ export declare interface MountChatWidgetOptions {
     logoUrl?: string;
     /** Show the agent name above assistant messages. Defaults to `false`. */
     showAgentName?: boolean;
+    /** Render assistant messages inside a filled bubble (themed via `agentBubbleBg`). Defaults to `false`. */
+    agentBubble?: boolean;
+    /**
+     * Show the header bar (title, logo, and the side-panel close "×"). Set `false`
+     * to drop it, e.g. when the host page already frames the widget. Defaults to
+     * `true`. Note: with the built-in launcher in side placement, the close "×"
+     * lives in the header, so hiding it leaves the launcher (and `widget.close()`)
+     * as the way to dismiss the panel.
+     */
+    showHeader?: boolean;
     /**
      * Theme overrides so the panel blends into the host page.
      */
@@ -822,6 +870,25 @@ export declare interface MountChatWidgetOptions {
         id: string;
         content: string;
     }) => void;
+    /**
+     * Called when a form collector submits successfully. `result` is the raw submit
+     * response (the third-party API's answer); `values` are the submitted fields.
+     * Forwards the client's `form:submitted` event.
+     */
+    onFormSubmitted?: (data: {
+        name: string;
+        values: Record<string, unknown>;
+        result: unknown;
+    }) => void;
+    /**
+     * Called when a form collector submit fails at the network/server level.
+     * Forwards the client's `form:error` event. No notice is shown in the chat.
+     */
+    onFormError?: (data: {
+        name: string;
+        values: Record<string, unknown>;
+        error: string;
+    }) => void;
 }
 
 /**
@@ -979,6 +1046,8 @@ export declare interface WidgetTheme {
     border?: string;
     /** Secondary accent: source badges and suggested-reply hover outline. (`--ago-accent-color`) */
     accent?: string;
+    /** Background of assistant message bubbles when `agentBubble` is on. Defaults to a light gray. (`--ago-agent-bubble-background`) */
+    agentBubbleBg?: string;
 }
 
 export { }